Axiom Specification v0.1

Axiom definitions are grouped into models. A model contains collection of related definitions that form a consistent group of data types for a specific use.

Models are defined using model statement. Each model needs a name and namespace declaration.

Model is identified by its namespace. Namespace is a globally-unique identifier in URI form.

Model name is a short string that is used mostly for diagnostic reasons. Model name can be displayed in error messages, diagnostic output and it can be used for similar purposes.

There is no strict requirement for model name to be unique. However, there is a benefit in making the name unique with reasonable probability. Model name is used as a default prefix for the model namespace, therefore it is recommended to keep model name short. It is recommended to use kebab-case for model names.

Axiom defines basic concepts for data modeling - items, values and data types.

Axiom provides following built-in simple types:

One model can be referenced from another model for reuse or extension. Models can be references by import statement:

Import statement prepares the base model for use in extended model. The statement also sets prefix for the base model. Types and items from the base model may be referenced by using base: prefix. For example, type Foo from the base model can be used in the extended model by referring to it as base:Foo.

Model name will be used as a default prefix when model is imported. Therefore the import statement above can be shortened as:

Import of a model creates a dependency on that model. Consequences of that dependency depend on specifics of reuse. For example, subtyping creates a strong dependency, while augmentation creates a weak one. But import and reuse always create a dependency - at the very least a dependency that the imported model exists.

Model imports may be circular. However, great care must be taken when working with circular dependencies. As a rule of thumb it is strongly recommended to avoid circular dependencies whenever possible.

Axiom allows subtyping (type derivation) for both simple and structured types. Derived simple type may limit possible value set by imposing restrictions. Derived structured type may introduce additional items (properties, container, object references).

Mixin is a data structure designed to be included in other data structures. Use of mixins is similar to inheritance used in subtyping, but it is not bound to subtyping and therefore it does not need to follow type hierarchy.

The mixin is seamlessly integrated into the data type:

Mixins are used when a set of items is repeated in may data types. It would be possible to just copy definitions of such items. But that would not be really readable and maintainable, especially if the items have structured type definitions, documentation or other annotations. Mixins make it all easier, bundling all the complexity in a single definition and then allowing its reuse. There is also a benefit for platforms that are generating code from the models, as mixins can be translated to native programming language concepts (e.g. Java interfaces).

However, all of that does not change the basic fact that mixin use is just a simple inclusion of items into the data structure. Therefore there are downsides. Data type that is using a mixin is tightly bound to the mixin definition, similarly to subtyping. Therefore great care must be taken when using mixins from different models.

Augmentation is a method how to extend capabilities of an existing data type without definition of a new data type.

Example model augments midPoint User type with custom property personIdentifier. Whenever the User data structure is used, the personIdentifier property may be used with it.

However, the personIdentifier property needs to be fully qualified with namespace information to distinguish it from any other properties that the midPoint model can have in the future.

Augmentation is usually used to extend capabilities of a different model, a model that we do not control. Therefore it is an ideal tool for customization of data models. For example, midPoint is a product with a fixed data model set when the product was released. But there is often a need to customize and extend the data model at "deployment time", long after the software was released. Augmentation is an ideal mechanism for that. A customer data model can augment fixed data structures of midPoint with custom items.

Augmentation is designed to be safe with respect to data model evolution. As long as the original data model evolves in an compatible way, the augmentation will still work. Both the original data model and the augmentation may evolve independently. The models will not get into conflict. But there is a price to pay. Augmentation data always have to use full namespaces to make the augmentation safe.

Axiom provides a means for a documentation integrated into the data model specification:

Axiom documentation is formatted in AsciiDoc. Only basic asciidoc formatting should be used, formatting that one would use inside of a simple section. Such as character formatting (bold, italics, monospace), paragraphs, bullet lists and so on. Headings and similar "outline" formatting should not be used. Axiom processors will take care of generating document outline, headers and similar document infrastructure.

Unlike most other languages, Axiom goes wider and deeper, working with concepts that are beyond and the data and under the data. Axiom supports concept of metadata, that are data about data. Metadata can be attached to every data value, describing data origin, transformation and so on. Axiom also supports concepts of partial, incomplete or unknown data values.

All of that is allowed by a concept of inframodel, which is model under the data. Inframodel deals with data items and values. E.g. metadata are implemented by extending the inframodel of Axiom value, which allows to attach metadata structures to every value of the data.

Dealing with inframodel is quite an advanced abstraction. However, the inframodel is usually hidden from most Axiom users.

None of the usual representation formats have sufficient support for such abstract "meta" and "infra" concepts. This is, in fact, quite understandable. Such formats originated in different times and they were built for different purposes. The need to support inframodel was not there when XML was created and when JavaScript object notation was (ab)used for general-purpose data representation. Therefore transition to inframodel is usually denoted by use of special characters in representation formats. Whenever you see at character (@) in JSON or element starting with underscore (_) in XML it is most likely an inframodel concept.

Please see Axiom concepts explanation for more details about such advanced topics.

Axiom is a self-descriptive language in a way that Axiom language can be described by Axiom language.

Namespace is a globally-unique identifier of a model. Each namespace specifies exactly one model. Whenever a data file needs to specify the data model that was used to create it, namespace is used to identify that model. Whenever a data model refers to a concepts of another model, namespace of the model is used. Whenever there is may be an ambiguity about appropriate interpretation of an item, namespace is used to resolve the ambiguity by pointing to the correct model.

All data models evolve. They change to implement new features, adapt to changes environment or fix mistakes of the past. Axiom is designed to combine, reuse and extend data models. Each model has its own namespace, therefore it may look like each model can evolve independently. However, there are practical limitations.

Some models are tightly interweaved. They depend on one another and if one of them changes the other has to adapt. This is usually caused by type inheritance. The problem is, that even if the "parent" model evolves in an compatible way, the "child" (dependent) model may still be affected and it may be forced to change in non-compatible way. The bad news is that there is not much that we can about this unless we want to make data structures quite complicated, big and difficult to use. But the good news is that we usually do not need to do anything. Development of models that are such a tight relationship are usually well coordinated. Therefore such conflicts can usually be avoided or resolved by "out of band" means.

Then there are models that need to evolve independently and they are prepared to pay the cost. There are two "safe" methods to use: composition and augmentation. Composition is a mechanism to use data type from a foreign schema in my own data structures. Composition easy to use, it does not complicate the data and it is overall a recommended mechanism. Augmentation is a mechanism to extend data type from foreign schema with custom items. Augmentation ensures safe evolution of the models. But it is using explicit specification of namespaces in the data, therefore it makes the data larger and more complex.

See Cross-model use cases for more details.

Axiom, similarly to other languages and platforms is using a concept of qualified name. Known as QName, qualified name is a combination of a local name with the namespace. E.g. an item foo specified in model identified by namespace http://schema.example.com/ns/bar will have a QName that is a combination of these two values. QNames are used to create globally-unique identifiers for all elements of data models, making sure that they will not be confused.

WWW architecture that states that QNames should be considered equivalent to URIs. But we have gone one step further in Axiom and we consider QNames to by just a special case of URIs. We define a mapping between QNames and URIs, which means that all QNames can be represented in URI form.

The QNames are mapped to URIs by concatenating namespace URI and a local name. If URI does not end with slash (/) or hash (#) character, hash (#) is concatenated to the URI before adding the local name. The URI-QName mapping is the reverse process. Local names must not contain hash or slash characters.

The recommendation is that model namespace name should not end with hash (#) or slash (/) character, so the hash (#) is assumed at the end. All the QNames used in a single model are related and part of one consistent group. We want to be perform a single fetch of the model specification to get definition of all the elements in the model.

Axiom QNames and URIs are almost the same thing. This means that URI can be used anywhere where QName is expected — as long as the URI is well-formed and QName can be derived from it. There is no special format for QName in Axiom. We do not need that. We are using URI format instead.

Axiom is reusing the concept of QName that is also used in other languages, such as XML. However, QNames can be quite a strange animal, especially when used in XML ecosystem. We are not promising that Axiom could deal with all the possible uses of QNames in the XML world, semantic web or in various JSON extensions. That is not our goal as that would complicate the system to the point where it may not be maintainable any more. Our goal is the other way around: QNames and concepts specified in Axiom should be usable in other ecosystems, as long as the ecosystem supports all the necessary concepts. E.g. It should be able to, theoretically, translate Axiom data models into XSD or JSON Schema and used them in XML or JSON worlds. However, if you use the concept of metadata, you are probably out of luck with XML or JSON, as those do not support metadata concepts at all.

Each model should be identified by exactly one namespace. Namespaces are URIs and not URLs, therefore they do not need to change. That is the theory. But in practice the namespaces do change. Even URIs are usually based on domain names that change. URI structure may change in time. Company names change, product names change, people make mistakes that need to be fixed and so on. Therefore namespaces change too.

Axiom models are identified by exactly one primary namespace. This namespace is used for all the usual purposes, especially when data are stored and serialized to representation formats. However, when we read the data, we tolerate other namespaces as well. Those are namespace aliases. Those may be data stored with a namespace before it was changed. We want to be able to read them and process them. But whenever we present or store the data, we will always use primary namespaces.

Namespace aliases are also a nice way how to solve the http vs https confusion.

Namespace URIs are usually quite long and it may be quite cumbersome to use them in representation data formats. Therefore Axiom has a concept of namespace prefix. Prefix is a short string that identifies the namespace. For example the Axiom model namespace https://schema.evolveum.com/ns/axiom/model is usually using axiom-model prefix. Prefix can be used at appropriate places instead of full namespace URI. Therefore, given the axiom-model prefix above, the following two notations are usually equivalent:

Namespace prefixes are usually specified in the model. Model name is used as a namespace prefix by default.

Specific syntax of the prefixes, rules about where prefixes can be used or cannot be used and other details depend on specific representation format.

Axiom namespace prefixes are similar to namespace prefixes in other languages (XML, XPath), but there are subtle and important differences. The most notable difference is that prefixes are semantically significant. Which means that if prefix is changed, meaning of the items and values may change as well. This is a critical difference with respect to the XML world. Unlike XML, prefix are usually defined in the model (schema), not in the document. The document may provide prefix declaration, but those are often redundant and may be omitted. The processor may refuse to process a file where prefix declaration is in conflict with the prefixes specified in the model. It is expected that processors will make some effort to process data with conflicting prefixes and try to "fix" them. However, this may not be possible under some circumstances, therefore processors are allowed to refuse such data.

Namespace prefixes are given by the model and they are considered to be immutable. Change of namespace prefix is considered to be an incompatible change. Prefix change is very likely to require data migration process.

Of course, making prefixes significant and immutable results in requirement that prefixes have to be unique. However, Axiom do not require global uniqueness of the prefixes. Prefixes need to be unique only in a particular data set. Axiom assumes that a models for all the data in the system are (eventually) known. As prefixes are controlled by the models, it is feasible to make prefixes unique in the entire schema. Which also makes prefixes unique in the entire data set.

However, prefix names have to be chosen wisely to allow evolution of data models. It is not difficult to make sure that the prefixes are not in the conflict today. But we also need to make sure that the prefixes will not conflict in the future when data models evolve and new models are introduced into the schema. Prefixes of Axiom models start with axiom-, which should be considered to be a reserved segment of prefix namespace. Models built on Axiom should adopt a similar convention to avoid future prefix conflicts. Use of project name in the prefix is a recommended practice. E.g. Prism model prefixes start with prism- and midpoint prefixes start with midpoint-. It is usually not a big issue to choose a longer prefix for primary model namespace, as that prefix is almost never used in the data. The data that are given by the primary model are almost always written without any namespace at all, as the namespace can be determined from the model. The prefixes are significant for metadata models or "extension" models that extend primary data model by using augmentation.

Names that are using the prefix notations are often used in the same place where URIs can be used in the representation formats. Therefore there is slight chance that prefix can be confused with URI scheme. For example, specifying prefixes such as http, https and especially urn are not a good idea. URIs usually have more complex internal structure than simple "qualified" names that use prefixes, therefore a chance to confuse prefix and URI are minimal. But there is still non-zero chance of conflict. Therefore, specifying namespace prefix that matches any of currently used URI schemes is strongly discouraged. Prefixes are specified in the models, as are namespace URI. Therefore model authors can make sure that prefixes and URIs are conflict-free. For data compatibility reasons, in case that a prefix conflicts with URI scheme, the prefix takes precedence.

Prefixes are completely optional. Axiom can be used without prefixes at all, if needed. It will be less efficient and perhaps less elegant, but everything will be strict, correct and fully-qualified. Such representations of Axiom data are called portable formats. Axiom is designed to work inside a single application, processing data for that application only. Portable data extend this notion, as they can be safely passed from one system to another. Portable formats make sure that every value or every item can be unambiguously interpreted in a different system that has the same primary data model, but that may have a different set of additional data models in its schema.

Use of prefixes may be problematic in applications that adopt an open world view. Use of prefixes in such applications that is not recommended.

Choosing a namespace URI is am important decision. Even though there are namespace aliases and Axiom can tolerate namespace changes, frequent namespace changes are confusing and they should be generally avoided. It is recommended to choose a good namespace URI from the beginning and then stick to it for years or even decades. Following paragraphs provide recommendations for choosing good namespace URI.

Generally, it is recommended to use HTTPS uri based on the DNS domain that you control. We recommend following format:

The best strategy is to keep the namespace URI short. Long namespace URIs are an obstacle for readability. Also, namespace URIs need to be stored together with the data under some circumstances therefore long URIs are increasing storage size of the data.

Strictly speaking, those are URIs, therefore there is no requirement for them to be resolvable URLs. However, we strongly recommend to choose URIs that can be made resolvable in the future. There may be great benefit in simply issuing an HTTPS request to the namespace URI to retrieve an definition or to use that URI as an endpoint for model-related services. Using a dedicated host part of the URI (e.g. schema.example.com) is a good strategy. Such host can be implemented as DNS alias to point to an appropriate server that hosts actual definitions or API.

Due to the possibility of future resolvability of the namespaces it is recommended to use https URI scheme instead of http.

Do not end your namespace URIs with slash (/) unless you have very good reasons to do so. Ending the namespaces with a slash will affect the way how QNames are created from the namespace. Do not end your namespace URIs with hash (#) either. Hash character will be automatically used when composing QNames if the URI does not end with a slash. Therefore appending hash character to your URI is redundant. It also makes your URI look strange and confusing.

Do not include model version in your URI. Axiom has a separate versioning mechanism and it does not rely on version numbers in namespaces. On the contrary, version numbers in namespace URI are likely to be an obstacle for organic evolution of your data models.

In case that you need to maintain several models in your project, it is recommended to create a component hierarchy in the namespaces, such as:

Following namespaces are used for definition of fundamental Axiom concepts:

The concept of Axiom namespaces is similar to namespace concepts in other ecosystems. Namespaces used by XML, semantic web and JSON-LD are quite similar to Axiom namespaces. This similarity is part of Axiom design, as we hope to be compatible with concepts and data from other ecosystems. However, Axiom namespaces are used in quite a different way. Unlike JSON, the namespaces are integral part of the design. And unlike XML, namespaces are used just where they are needed. We hope that this approach helps Axiom to be both reliable and user-friendly platform.

Item path fully supports concept of namespaces. There are two ways how to specify namespaces: using full URIs and using namespace prefixes.

URIs in the item path must be enclosed in parenthesis:

Namespace prefixes can be used in item path instead of URIs:

The example-custom prefix above represents namespace https://schema.example.com/custom.

Axiom is designed to seamlessly support multi-value data. However, referring to items in hierarchical data structures where multiple values are possible is not entirely straightforward. Let’s consider following data structure:

There is a typo in the description of the second assignment. We want to refer to that specific value to have it fixed (e.g. by using a delta-based modify operation). However, the path assignment/description is ambiguous, as it does not specify which values of assignment it refers to.

Therefore path segments may contain optional identifier:

The way how the identifier is interpreted may be slightly different for every item or data type. The details are specified in the model.

Item paths are usually relative. The root of the path resolution is usually implicit. For example the activation/administrativeStatus is usually relative to the top of the object.

Root of the path resolution can be specified explicitly by using the dollar sign ($):

This path is an absolute path, its root is specified by symbol focus. Meaning of focus is implementation-specific. It may be identifier of an object, it may be name of the variable or it may be anything else. The root symbol is considered to be qualified name, therefore it may even be an URI or URL of a network service:

There are two principal uses of item path:

Use case: jpegPhoto was not fetched from repository and we do not know whether it has a value or not.

There is an issue that the completeness is a property of jpegPhoto item, not a particular value. But we cannot express data about an item if there is no value present. Hence the nil. The nil indicates that this value is not really a value.

The @value=null may be optional, as this is a hash and no value is specified this should be obvious.

Use case: password is present, but we cannot or do not want to disclose the value. However, we want to indicate that there is a password.

Value significance is used to denote a negative value, metadata are attached as usual.

Metadata serialized with data:

Metadata structures are specified using a special metadata keyword:

This statement defines a new data type StorageMetadata with items createTimestamp and modificationTimestamp. The data type will be registered as value metadata with item name storage. The metadata will appear mixed into the data:

Metadata can be attached even to items without a value.

It would be theoretically possible to have data about metadata, thus creating metametadata. However, Axiom does not have ambitions for this, at least not in its early versions. Axiom assumes just one "meta" level and it does not apply metadata definitions to the metadata.

Recommended format for version number is:

All three parts are usually numeric, e.g. 4.2.1. The parts of version number have specific meaning:

Version number that are zeros are optional. Therefore version 1.2 is to be considered the same as version 1.2.0. Minor and major version numbers must be numeric. It is strongly recommended for patch version number to be numeric too. However, it is allowed for it not to be numeric to account for hotfixes and other out-of-sequence patches.

In addition to that, version number may have optional suffix:

The suffix indicates that the model version is before or lower than the specified version. E.g. 1.2-SNAPSHOT means that this is a model that is just before version 1.2. Therefore it is considered to be after any 1.1 version, including 1.1.2 and 1.1.98761, but not yet reaching version 1.2. The suffix is usually used for development, milestone or pre-release versions. Ordering of the suffixes is not specified. Therefore it is not specified whether 1.2-M3 is before or after 1.2-RC2.

Axiom requires data compatibility between minor versions of data model. This means that data created for earlier version of the model must be comprehensible for models of later versions. No data migration or transformation should be necessary.

However, there are few exceptions:

This has to be decided in later versions of Axiom.

TODO: use of version in import

This has to be decided in later versions of Axiom.

TODO: specification of model version in the data

Axiom is designed to support evolution of data models. There are special tools that support data model versioning and version-aware documentation.

Following markers can be applied to any modeling concept (type, item, etc.)

This has to be decided in later versions of Axiom.

TODO: removal of deprecated elements

TODO: deprecation "contract" vs compatibility: when we can remove deprecated items? minor or major version?

Experimental concepts of the model can change in any way at any time. Such concepts are being developed. They are unstable. People that are using experimental parts of the model must be prepared to adapt the data after every change of the model, including minor and patch versions of the model.

Experimental concepts usually evolve into ordinary concepts eventually. But that may take several versions.

Experimental concepts may even be removed at any time if they prove to be wrong or undesirable. The developers are not required to provide any replacement functionality for removed experimental concepts.

Models with major version of zero (0) are considered to be completely experimental. Every concepts of such model should be considered experimental. There are no compatibility guarantees for models with zero major version number.

Axiom is data modeling language used to model data and metadata for Prism and midPrivacy project, with intention to replace XSD as go-to modeling language for Prism.

Axiom is designed with migration path from XSD to Axiom in mind, which is possible thanks to common mapping of concepts via Prism. Axiom maps more directly to Prism concepts and it is intended to be less verbose than same model written in XSD.

Axiom is developed in an incremental fashion. The focus is on practical use and overall usefulness of Axiom. We have no ambition for Axiom to become a universal language suitable for every situation. Axiom is designed for use in applications.

Axiom is built on solid foundations. We are paying a lot of attention to make sure that the basic principles of Axiom are correct and consistent and that Axiom can evolve in the future. But all the details of Axiom are not laid out yet. However, first versions of Axiom are not going to be perfect. It will be limited and there may be mistakes that need to be corrected in the future. However, Axiom can be validated only by practical use of the language in prototypes and real-world implementations. Therefore the primary goal of Axiom effort is to allow for such implementations to allow Axiom to continually improve. Each new version of Axiom should be better, more detailed, better documented, more polished.

Axiom specification will progress from initial draft to early versions, prototypes, specification improvements, validation using initial implementations, progressing in iterations. Language specifications will go hand in hand with implementations. Primary implementation of Axiom is available under open source license and developed in the open source way.

Axiom may get standardized eventually. But we want to avoid premature standardization. We see standardization as the very last step in Axiom development. Before we get to standardization, we need to make sure that Axiom is good enough and that it works. That has to be proven by several independent implementations and the language needs sufficient time to mature.

Axiom was created and it is maintained by Evolveum.

Initial version of Axiom was developed in MidPrivacy project that was supported by funding from NGI_TRUST program.