AML document model
AML documents defines a small vocabulary defining modular documents that all AML processors must support when generating the JSON-LD output with the outcome graph of metadata.
The following AML Vocabulary describes the document ontology:
#%Vocabulary 1.0 base: "http://a.ml/vocabularies/document#" external: shacl: "http://www.w3.org/ns/shacl#" usage: Document Model vocabulary for AMF. The Document Model defines the basic modular units where domain descriptions can be encoded. classTerms: BaseUnit: displayName: Base Unit description: | Base class for every single document model unit. After parsing a document the parser generate parsing Units. Units encode the domain elements and can reference other units to re-use descriptions. properties: - references Document: displayName: Document description: | A Document is a parsing Unit that encodes a stand-alone DomainElement and can include references to other DomainElements that reference from the encoded DomainElement. Since it encodes a DomainElement, but also declares references, it behaves like a Fragment and a Module at the same time. The main difference is that the Document encoded DomainElement is stand-alone and that the references declared are supposed to be private not for re-use from other Units extends: [Fragment, Module] Module: displayName: Module description: | A Module is a parsing Unit that declares DomainElements that can be referenced from the DomainElements in other parsing Units. It main purpose is to expose the declared references so they can be re-used extends: BaseUnit properties: - declares Fragment: displayName: Fragment description: A Fragment is a parsing Unit that encodes a DomainElement extends: BaseUnit properties: - encodes DocumentExtension: displayName: Document Extension description: A Document that extends a target document, overwritting part of the information or overlaying additional information. extends: Document ExternalFragment: displayName: External Fragment description: A fragment with including raw information that cannot be semantically processed, the information is encoded as a raw opaque textual description. SourceMap: displayName: Source Map description: | SourceMaps include tags with syntax specific information obtained when parsing a particular specification syntax like RAML or OpenAPI. It can be used to re-generate the document from the RDF model with a similar syntax DomainElement: displayName: Domain Element description: Base class for any element describing a domain model. Domain Elements are encoded into fragments properties: - sources RootDomainElement: displayName: Root Domain Element description: Domain element that is the entrypoint for a domain description. Domain elements encoded in Documents must be RootDomainElements. extends: DomainElement ExternalDomainElement: displayName: External Domain Element description: Domain element containing foreign information that cannot be included into the model semantics extends: DomainElement properties: - raw LinkableElement: displayName: Linkable Element description: | Reification of a link between elements in the model. Used when we want to capture the structure of the source document in the graph itself. Linkable elements are just replaced by regular links after resolution. properties: - link-label - link-target CustomDomainProperty: displayName: Custom Domain Property description: | Definition of an extension to the domain model defined directly by a user in the RAML/OpenAPI document. This can be achieved by using an annotationType in RAML. In OpenAPI thy don't need to be declared, they can just be used. This should be mapped to new RDF properties declared directly in the main document or module. Contrast this extension mechanism with the creation of a propertyTerm in a vocabulary, a more re-usable and generic way of achieving the same functionality. It can be validated using a SHACL shape AbstractDeclaration: displayName: Abstract declaration description: | Graph template that can be used to declare a re-usable graph structure that can be applied to different domain elements in order to re-use common semantics. Similar to a Lisp macro or a C++ template. It can be extended by any domain element adding bindings for the variables in the declaration. properties: - variables Variable: displayName: Variable description: Variables that can be replaced in the abstract declaration Example: displayName: Example description: Example for a particular domain element properties: - value - strict propertyTerms: references: displayName: references description: | The references relationship makes public that some DomainElement within this Unit includes a DomainElement within other unit. It can be used to track references between units at the document level. range: DomainElement encodes: displayName: encodes description: The encodes relationship links a parsing Unit with the DomainElement from a particular domain the unit contains. range: DomainElement declares: displayName: declares description: | The declares relationship exposes a DomainElement as a re-usable unit that can be referenced from other units. URIs for the declared DomainElement are considered to be stable and safe to reference from other DomainElements. range: DomainElement extends: displayName: extends description: | Entity that is going to be extended overlaying or adding additional information The type of the relationship provide the semantics about thow the referenced and referencer elements must be combined when generating the domain model from the document model. range: Document sources: displayName: source description: Indicates that this parsing Unit has SourceMaps range: SourceMap raw: displayName: raw description: Raw textual information that cannot be processed for the current model semantics. range: string link-label: displayName: link label description: Label for the type of link range: string link-target: displayName: link target description: Uri of the linked element range: DomainElement schema: displayName: schema description: Data shape associated to one property that can be used to validate values of that property. range: shacl.Shape variables: displayName: variables description: Variables to be replaced in the graph template introduced by an AbstractDeclaration range: Variable deprecated: displayName: deprecated description: Indicates that a particular domain element definition is deprecated range: boolean value: displayName: example value description: value of one example as a string encoded in some media type range: string extends: raw strict: displayName: strict example description: Indication that this example is meant to be stritly valid according to the domain element semantics, not just a reference range: boolean