Simple Domain Modeling Language
Language Reference

A model is an informative representation of an object, person or system. The term originally denoted the plans of a building in late 16th-century English, and derived via French and Italian ultimately from Latin modulus, a measure. As is common in software development the term model is overloaded and it’s use can lead to confusion as people have different expectations and assumptions regarding what kind of model is being discussed. To this end we introduce some terminology here that, if simply used as model qualifiers, helps to disambiguate the purpose of any particular model.

For now we will use the following classification to partition the major purpose of different model instances.

• Data: A data model in software engineering is a representation of concepts and the relationships, constraints, rules, and operations to specify data semantics for a chosen domain of discourse. Typically it specifies relations between kinds of things, but may also include relations with individual things. It can provide sharable, stable, and organized structure of information requirements or knowledge for the domain context.
• Behavior: Behavioral languages are designed to describe the observable behavior of complex systems consisting of components that execute concurrently. These languages focus on the description of key concepts such as: concurrency, nondeterminism, synchronization, and communication.
• Process: [Business] process modeling (BPM) in business process management and systems engineering is the activity of representing processes of an enterprise, so that the current business processes may be analyzed, improved, and automated.

A common framework for defining the level of abstraction inherent to a model are the three perspectives introduced by ANSI in 1975 (introduced in section 1.3.

• Conceptual: In the field of computer science a conceptual model aims to express the meaning of terms and concepts used by domain experts to discuss the problem, and to find the correct relationships between different concepts. The conceptual model attempts to clarify the meaning of various, usually ambiguous terms, and ensure that confusion caused by different interpretations of the terms and concepts cannot occur.
• Logical: A logical data model or logical schema is a data model of a specific problem domain expressed independently of a particular database management product or storage technology (physical data model) but in terms of data structures such as relational tables and columns, object-oriented classes, or XML tags. This is as opposed to a conceptual data model, which describes the semantics of an organization without reference to technology.
• Physical: A physical data model (or database design) is a representation of a data design as implemented, or intended to be implemented, in a database management system. In the lifecycle of a project it typically derives from a logical data model, though it may be reverse-engineered from a given database implementation.

With these two classifications we can construct a simple grammar for the qualification of the term model:

Perspective    = "conceptual" | "logical" | "physical"

Scope          = "data" | "behavior" | "process"

ModelReference = Perspective, Scope "model"

There have been a number of modeling techniques, notations, and languages over the years. The following table describes those in common use today. It is worth noting that after OMG standardization there are common meta-model underpinnings for UML and BPMN.

1. Class and Component diagrams.
2. Sequence, State, and Activity diagrams.
3. Use Case and Activity diagrams.
4. Event-driven Process Chains.
5. Information Engineering (IE) introduced the commonly used crows-foot notation.
6. Action Semantics and action languages.

UML has a built-in extension mechanism with stereotypes and profiles and data modeling concerns are often introduced with specific extensions such as stereotypes for different key types.

The reasons for embarking on a domain modeling exercise vary from informational to transformational. However, there are a number of

(TODO: Complete this section)

Commonality

Variability

Inheritence

…

Interface and Implementation

…

(no term)

Scope: Breadth and Depth

Domain-driven design (DDD) is a software design approach focusing on modeling software to match a domain according to input from that domain’s experts. Under domain-driven design, the structure and language of software code (class names, class methods, class variables) should match the business domain.

Within this approach the domain model is usually a conceptual or logical data model that describes the key entities that comprise the domain. The representation of this model can be any of the languages described above although UML is the common. The discipline of domain modeling is unique in it’s focus on deriving data/information models directly from the business and stresses the involvement of domain experts from the business in the development of models. Additionally the literature describes specific kinds of model entities and their unique semantics, Entities, Value Objects, Events, and Aggregates, etc. which help focus conversations on key modeling concepts such as identity, lifecycle, and ownership.

Thus, a Domain Model is a conceptual (UML or Ontology) or logical (UML) data model developed according to a specific methodology (DDD) and employing a specific meta-language (UML Profile).

Some of the defined kinds, Repository, Factory, and Service are lower-level concerns and the lack of a clear separation between different levels of abstraction is one criticism of the method. Additionally terms such as Entity as defined by DDD are not entirely compatible with the use in pre-existing methods such as E/R modeling.

However, the method’s focus on the business and it’s vocabulary as the basis for models is valuable in an effort such as the Universal API where the model will represent our business model in different presentations.

The purpose of SDML is to be the source of truth concerning the enterprise’s domain, and the root of the tree shown in figure 5. It needs to provide an abstraction that is expressive enough to model the structure of entities that define the domain, while providing enough detail to be useful in transforming to the next level of more concrete models and artifacts.

SDML has two key tenets that help in this goal:

1. Provide the ability to capture correct, but incomplete models to allow fast capture of key information first.
2. Provide an extension mechanism that goes beyond marker values and allows semantic extension when necessary.

Additionally, by focusing first on a text-based syntax we provide a resource representation that fits well into most software processes, it can be version controlled, it’s diff-friendly, you can use code-reviews and pull-requests to build governance processes. While this document does not preclude alternative representations, including visual ones, the surface syntax is the canonical authoring form.

(TODO: Add data dictionary discussion)

(TODO: Add vocabulary discussion)

(TODO: Complete this list)

1. Versioning
2. Object Modeling
3. Behavior Modeling
4. Standardization

A qualified identifier comprises a module identifier followed by the Colon (“:”, U+003A) character and the identifier of a member within that module.

QualifiedIdentifier
    ::= Identifier ":" Identifier

A type reference may be to a locally defined type by an identifier, or an imported type by a qualified identifier.

IdentifierReference
    ::= QualifiedIdentifier | Identifier

ModuleBase
    ::= "base" IriReference

The keyword base provides the base IRI for the module and corresponding RDF schema or OWL ontology. This corresponds to the use of the xml:base attribute in RDF/XML and the @base directive in Turtle and SPARQL¹². This IRI is used as a prefix for defined type names so that each type has a unique IRI. The example in listing 4 demonstrates the assigned IRI identifier for the structure type named Thing.

module example base <https://example.org/rdf/example#> is

  structure Thing
  ;; IRI: https://example.org/rdf/example#Thing

end

Module URI Resolution

Each module has an identifer/name defined within the module source as well as a base URI used to assign URIs to every model element within the resource. This URI identifier for each model element necessary as the identifier for the corresponding RDF resource(s). Our first problem is to determine the base URI for the module,as follows:

1. If the module has a base specifier it MUST be used as the module URI.
2. If the reader has access to an SDML catalog file (For details of the catalog file format see appendix 6.8), a matching catalog entry MUST be used as the module URI.
3. A URI is calculated for the module using the file: scheme and the file path relative to a project root.

Considering the following simple module in the file vehicle.sdm.

module vehicle is end

If the following file is in the same directory as the vehicle module it is possible to

{
  "base": "https://example.org/rentals/",
  "entries": {
    "vehicle": {
      "item": {
        "relative_uri": "vehicle#",
        "relative_path": "vehicle-v1.sdm"
      }
    }
  }
}

ModuleBody
    ::= "is"
        ImportStatement* Annotation* Definition*
        "end"

To import types from other modules you add one or more import statements to the module body. Each statement may reference one or more module names or the qualified name of a type within a module.

ImportStatement
    ::= "import" ( Import | "[" Import+ "]" )
Import
    ::= MemberImport | ModuleImport

Importing a module allows access to all members of that module using qualified identifiers. For example, importing module sdml allows the reference of core types as sdml:string or sdml:decimal.

ModuleImport
    ::= Identifer

Importing a module member directly still results in a qualified identifier, but makes the dependency clearer. For example, in the case above if we are only using the string member from the sdml module importing sdml:string is cleaner.

MemberImport
    ::= QualifiedIdentifier

The module in listing 5 contains a single import statement referencing the module named xsd making it’s members visible in the qualified form xsd:*.

module example is

  import xsd

end

The module in listing 6 contains a single import statement referencing the member named integer from the module xsd making it visible.

module example is

  import xsd:integer

end

To reduce the number of import statements a list of identifiers, both module and member, may be referenced as a list. Listing 7 makes the members author and title from the module dc visible. Lists in SDML start with the Left Square Bracket (“[”, U+005B) character and end with the Right Square Bracket (“]”, U+005D) character with no separator character between members of the list.

module example is

  import [ dc:title dc:author ]

end

The members of a module are a set of definitions that may be combined to develop a domain model.

Definition
    ::= DataTypeDef
        | EntityDef
        | EnumDef
        | EventDef
        | PropertyDef
        | StructureDef
        | UnionDef

Data types are further described in section 2.4; entities, enumerations, events, structures, and disjoint unions are described in section 2.7; and annotation properties are described in section 2.6.1.

A subset of the definition types in the EBNF above are types, and the complete type model for SDML is shown in figure 6. In this figure the following types exist that are not directly reified in the surface syntax.

Any

The root of our type system, or the type of all individuals. This is sometimes termed top or a tautology ⊤.

Scalar

A scalar type refers to a data type whose individuals represent a single discrete value. In SDML all datatypes and enumerations are scalar types.

Sum

A type whose members are discrete but not necessarily scalar, i.e. it’s individuals are either one member or another, but not both. In the case of SDML only disjoint unions are sum types.

Product

A type whose members are all present, i.e. it’s individuals have one member and another and so on. In SDML entities, events, and structures are product types.

Unknown

A pseudo-type that is applied when the author does not yet know what the type should be but wishes to create a valid model. In SDML member types may be defined as unknown during module development but such a type, and therefore it’s containing module, is incomplete.

None

A type which represents the type of zero individuals and is therefore invalid as a member type. This is sometimes termed bottom or absurdity ⊥.

Sum vs. Product

Given a type \(T\) with members \(m_1, \cdots m_n\), and a relation \(\tau_{m_i}\) that returns the type of a value or definition, we can show this mathematically as follows.

1. Because a sum type may only be one member or another at any time the number of potential values (shown below as the cardinality of the type) is the number of values in each member added together \(m_1 + m_2 + \cdots m_n\).

   \[ \sum_{m \in T} |\tau_m| \]

2. Because a product type has it’s first member and second and so on, the number of potential values is the number of values in each member multiplied together \(m_1 \times m_2 \times \cdots m_n\). This is also known as the Cartesian Product of the set \(\{m_1, \cdots m_n\}\).

   \[ \prod_{m \in T} |\tau_m| \]

A boolean value in SDML is either a truth value, or a falsity value. Other types are not coerced into boolean values as they may be in other languages.

Boolean
    ::= Truth | Falsity

We denote a truth value with either the keyword true or the Down Tack (“⊤”, U+22A4) character.

Truth ::= ( “true” | “⊤” ) #+END_SRC

We denote a falsity value with either the keyword false or the Up Tack (“⊤”, U+22A5) character.

Falsity
    ::= ( "false" | "⊥" )

An unsigned value in SDML is a string of ASCII decimal digits, without leading zeros; zero, 0, is a valid value however 00 and 01 are not. The unsigned type corresponds to a 64-bit unsigned integer number (values \([0, 2^{64}-1]\)).

Unsigned
    ::= Zero | NonZero ASCII_DIGIT*
Zero
    ::= [0]
NonZero
    ::= [1-9]

A signed integer value in SDML consists of an optional a sign character (Hyphen Minus, “-”, U+002D or Plus Sign, “+”, U+002B) followed by a string of ASCII decimal digits, without leading zeros; zero, 0, is a valid value however 00 and 01 are not. The integer type corresponds to a 64-bit signed integer number (values \([−2^{63}, 2^{63} − 1]\)).

Integer
    ::= NumericSign? Unsigned
NumericSign
    ::= [+-]

A decimal (fixed point) value in SDML is an integer value, followed by the Full Stop (“.”, U+002E) character and another integer-like value although this second value allows any number of leading zeros. The decimal type corresponds to a 128-bit representation of a fixed-precision decimal number.

Decimal
    ::= Integer "." ASCII_DIGIT+

A double value in SDML is a decimal-like value followed by a lower or upper case letter E (Latin Small Letter E, “e”, U+0065 or Latin Capital Letter E, “E”, U+0045), a sign character (Hyphen Minus, “-”, U+002D or Plus Sign, “+”, U+002B) and an integer-like value. The double type is a 64-bit floating point number (specifically, the “binary64” type defined in IEEE 754-2008).

Double
    ::= Decimal ExponentChar NumericSign? Integer
ExponentChar
    ::= [eE]

A string value in SDML is a sequence of Unicode characters starting and ending with a Quotation Mark (’“‘, U+0022) character. While standard escape sequences allow for embedding non-printing characters.

String
    ::= QuotedString LanguageTag?
QuotedString
    ::= '"' ( Escape | NotAllowed )* '"'
NotAllowed
    ::= [^\"\#x00-#x08#x0B-#x1F#x7F]

Standard single-character escape forms are supported, described in table 4. The form \u{XXXX}, where X is a single hex digit, allows for the inclusion of any Unicode characters by their code point. Note that this form requires a minimum of 2 and a maximum of 6 such digits.

Escape              ::= "\\" ( CharacterEscape | UnicodeEscape )
CharacterEscape     ::= [\"\\/abefnrtv]
UnicodeEscape       ::= "u{" HexPair ( HexPair ( HexPair )? )? "}"
HexPair             ::= ASCII_HEX_DIGIT ASCII_HEX_DIGIT

Note also that strings allow literal newlines and do not require they be present in escaped form. This means that a string literal supports multiline forms.

A language-tagged string value in SDML is a string as above but immediately followed by a Commercial At (“@”, U+0040) character and an unquoted string of characters that conform to a language identifier. Note that both components of such a string contribute to equality tests, so that "abc"@en is not equal to "abc"@fr.

LanguageTag
    ::= "@"
        LanguageTagPrimary
        LanguageTagExtended?
        LanguageTagScript?
        LanguageTagRegion?

The primary language is one of:

• a two letter language code from ISO 639-1¹³,
• a three letter code from ISO 639-2¹⁴.

LanguageTagPrimary
    ::= ASCII_LETTER_LOWER ASCII_LETTER_LOWER ASCII_LETTER_LOWER?

The extended language is zero to three selected three letter ISO 639-2 codes.

LanguageTagExtended
    ::= "-"
        ASCII_LETTER_UPPER ASCII_LETTER_UPPER ASCII_LETTER_UPPER

The language script is an ISO 15924¹⁵ four letter code in title case.

LanguageTagScript
    ::= "-"
        ASCII_LETTER_UPPER ASCII_LETTER_LOWER
        ASCII_LETTER_LOWER ASCII_LETTER_LOWER

The language region is either a two letter ISO 3166-1¹⁶ code or a three digit UN M49¹⁷ code.

LanguageTagRegion
    ::= "-"
        ( ( ASCII_LETTER_UPPER ASCII_LETTER_UPPER )
          | ( ASCII_DIGIT ASCII_DIGIT ASCII_DIGIT ) )

An IRI reference value in SDML is a value IRI value, either absolute or relative, between a Less-Than Sign (“<”, U+003C) character and a Greater-Than Sign (“>”, U+003E) character. IRI references are more permissive in the SDML grammar than the Turtle¹⁸ language.

Iri
    ::= "<"
        ( [^<>\"{}|^`\#x00-#x20] | UnicodeEscape )*
        ">"

A binary value in SDML is a compact list of bytes that allows for the encoding of values that may not be possible with the other built-in types. The representation of a binary string is a sequence of bytes in hex pairs; the opening bracket of the sequence has a leading Number Sign (“#”, U+0023) character to differentiate from other sequence values. Note that whitespace is entirely optional, but recommended to layout the hex values.

Binary
    ::= "#[" HexPair* "]"

Here is an example showing a common layout with 16 bytes per row in two blocks of 8.

module example is

  import ex

  @ex:thing = #[
    52  32  39  76  5a  43  42  43    65  57  55  67  51  33  4a  31
    5a  57  77  67  56  32  39  79    62  47  51  4b
  ]

end

While the value 101 is defined to be an Integer literal, in the presence of sub-types how do you specify the type of a literal? To accomplish this a value constructor allows for specifying the precise type, or casting a value to a specific type.

The syntax appears as a function call with a type reference followed by a valid simple value surrounded by the Left Parenthesis (“(”, U+0028) and Right Parenthesis (“)”, U+0029) characters. The literal value MUST be valid for the referenced type, or one of it’s super-types.

ValueConstructor
    ::= IdentifierReference "(" SimpleValue ")"

Here we assert that the value 1 is an unsigned rather than the default signed integer.

module example is

  import ex

  @ex:thing = xsd:unsigned(1)

end

You can ignore the syntax of @ex:thing which is an annotation, see section 2.6, used to ensure the syntax is complete for all examples.

A mapping value denotes a functional relationship between the domain (left-hand value) and range (right-hand value).

MappingValue
    ::= SimpleValue HasType Value

Mapping values are most often used within lists to create dictionary-like structures.

module example is

  import ex

  @ex:dictionary = [
    "yes" -> 1
    "no" -> 2
    "maybe" -> 3
  ]

end

As stated in section 2.3, sequences in SDML start with the Left Square Bracket (“[”, U+005B) character and end with the Right Square Bracket (“]”, U+005D) character with no separator character between members of the list. Sequence values are, as one might expect, sequences of values and specifically of simple values. Sequence value may also by heterogeneous and therefore contain elements of different types.

SequenceOfValues
    ::= SequenceValueConstraint? "["
        ( SimpleValue | ValueConstructor | IdentifierReference )+
        "]"
SequenceValueConstraint
    ::= "{"
        ( SequenceOrdering? SequenceUniqueness? )
        "}"

module example is

  import ex

  @ex:thing = [ "yes" "no" "maybe" ]

end

module example is

  import ex

  @ex:thing = {unique}[ "yes" "no" "maybe" ]

end

A datatype definition introduces a new simple data type by restriction of some existing base type.

DataTypeDef
    ::= "datatype" Identifier
        TypeRestriction "opaque"? DataTypeBase AnnotationOnlyBody?

TypeRestriction
    ::= "<-" | "←"
DataTypeBase
    ::= IdentifierReference | BuiltinSimpleType

Listing 13 shows the type restriction operator, <-, defining a new type named name as a restriction on the existing XML Schema data type xsd:string.

module example is

  import ex

  datatype Name <- string

end

While such a type is useful for conveying semantic meaning with types it doesn’t provide any actual restriction on the value space of the type. This is accomplished by using a subset of the facets described in XML Schema part 2 to specify constraints on the new type.

module example is

  import ex

  datatype Currency <- decimal is
    @xsd:fractionDigits = 3
  end

  datatype Price <- Currency is
    @xsd:totalDigits = 7
  end

end

Also, in listing 15 we now see that the Name type is a string whose length is between 5 and 25 characters only.

module example is

  import ex

  datatype Name <- string is
    @xsd:minLength = 5
    @xsd:maxLength = 25
  end

end

As we defined the new datatype Name as a kind of string it has all the properties (length, substring, etc.) of a string. However, in some cases we may want the underlying type to be inaccessible to clients and so we mark the datatype as opaque. The only operations that can be performed on an opaque type are equality and strict inequality.

module example is

  import ex

  datatype Name <- opaque string is
    @xsd:minLength = 5
    @xsd:maxLength = 25
  end

end

From OWL 2 Web Ontology Language Quick Reference Guide¹⁹:

Annotation Properties are an extension mechanism that interacts directly with the underlying RDF representation of the subject model element. While these may look like Java annotations, Python decorators, or Rust attributes it is more powerful in that it can express arbitrary statements about the model element. An SDML annotation starts with the symbol “@” and then has an identifier that resolves to an OWL annotation property (see section 2.6.3 for the detailed rules), and a value for the corresponding property range.

AnnotationProperty
    ::= "@" IdentiferReference "=" Value

The following example demonstrates a common annotation property attached to a module.

module example is

  import skos

  @skos:note = "This is an example annotation"

end

For descriptive annotation properties it is valuable to use the language specific string format so allow for localization of labels and descriptions. The following example shows a simple label specified in multiple languages.

module example is

  import skos

  @skos:prefLabel = [
    "example"@en
    "exemple"@fr
    "例子"@zh-CH
  ]

end

A model element may have any number of annotation properties, especially the module itself which often includes annotations for the domain itself.

module example is

  import [ dc skos xml ]

  @skos:prefLabel = "Example Module"@en
  @dc:description = "This is an example module, with two annotations."@en
  @dc:created = @xsd:date("2023-08-17 Thu")
  @dc:creator = <http://github.com/sdm-lang>
  @dc:license = <https://opensource.org/license/mit/>

end

From OWL Web Ontology Language Reference, Appendix E: Rules of Thumb for OWL DL ontologies:

If a property a is used where an annotation property is expected then it should either be one of the built in annotation properties (owl:versionInfo, rdfs:label, rdfs:comment, rdfs:seeAlso, and rdfs:isDefinedBy) or there should be a triple:

a rdf:type owl:AnnotationProperty

This section will only briefly introduce constraints as section 4 provides a detailed description. The first example, in listing 20, provides an informal constraint in that it is simply a string which is useful to readers but cannot be verified.

module rental is

  assert name_form = "All definition names MUST start with 'Rental'"

end

While informal constraints are not validated in any way, given the ambiguities of human language a controlled language is a useful alternative.

A formal constraint on the other hand may be verified, but takes more work to structure correctly. The example in listing 21 example above by methodically checking every definition and any members therein.

module rental is

  assert name_form is
    forall d in definitions(self), d.name.has_prefix("Rental")
  end

  assert name_form_alternate is
    ∀ d ∈ definitions(self) has_prefix(name(d) "Rental")
  end

end

In general only properties that have an RDF type of owl:AnnotationProperty, or are sub-properties of such a property, may appear as annotations. This maintains the assertion that they are annotations of their subject and allows the use of a range of pre-defined annotation properties from RDF, RDF Schema, OWL, and the Dublin Core Metadata Initiative (DCMI)²⁰.

For example the annotation property rdfs:comment is defined in the following manner allowing it’s use on any resource and with a value that may be any literal.

rdfs:comment rdf:type rdf:Property, owl:AnnotationProperty ;
    rdfs:isDefinedBy <http://www.w3.org/2000/01/rdf-schema#> ;
    rdfs:label "comment" ;
    rdfs:comment "A description of the subject resource." ;
    rdfs:domain rdfs:Resource ;
    rdfs:range rdfs:Literal .

To allow the standard library to define SDML equivalents of such properties it is necessary to provide a mechanism to use non-annotation properties such as rdf:type, rdfs:domain, and rdfs:range as demonstrated in the example above. To allow this, if a model element has the property rdf:type then the transformation from that element to RDF does not use any of the transformations described here but an explicit mapping from only the provided properties.

RdfThingDef
    ::= "rdf" Identifier RdfTypes? AnnotationOnlyBody
RdfTypes
    ::= "type" ( IdentifierReference | "[" IdentiferReference "]" )

Rewriting the RDF from listing 22 into SDML results in the definition in listing 23.

module rdf_schema base <http://www.w3.org/2000/01/rdf-schema#> is

  import [ rdf owl ]

  rdf Resource is
    ;; rdf:type -- rdf:Class is automatically implied
    ;; rdfs:label -- structure name is automatically implied
    ;; @isDefinedBy -- module base URL is automatically implied
    @comment = "The class resource, everything."
  end

  rdf comment type [ rdf:Property owl:AnnotationProperty ] is
    ;; rdf:type -- rdf:Property is automatically implied
    ;; rdfs:label -- property name is automatically implied
    ;; @isDefinedBy -- module base URL is automatically implied
    @comment = "A description of the subject resource."
    @domain = Resource
    @range = Literal
  end

end

The following are commonly used RDF and OWL definition properties.

Commonly used annotation super-types

• owl:AnnotationProperty
• owl:FunctionalProperty
• owl:InverseFunctionalProperty
• owl:SymmetricProperty
• owl:TransitiveProperty

A structure is a product type that is composed of named and typed members. A structure is therefore akin to a record type, a table in data modeling, or a class in object modeling.

StructureDef
    ::= "structure" Identifier StructuredBody?

As only the keyword structure and the identifier are required, the listing 24 is therefore a valid model.

module example is

  structure Length

end

The structure Length in listing 24 is valid but considered incomplete. Adding a body to the structure, between is and end, makes it complete even if it has no actual members. In listing 25 the structure Length is now complete.

StructuredBody
    ::= "is" Annotation* Member+ "end"

module example is

  structure Length is
    @skos:prefLabel = "Length"@en
  end

end

Listing 26 adds the members value and unit and their corresponding types.

module example is

  structure Length is
    @skos:prefLabel = "Length"@en

    value -> Decimal
    unit -> DistanceUnit
  end

end

EntityDef
    ::= "entity" Identifier EntityBody?

module example is

  entity Person

end

The entity Person in listing 27 is valid but incomplete.

EntityBody
    ::= "is"
        Annotation* EntityIdentity Member*
        "end"

module example is

  entity Person is
    identity id -> PersonId
  end

end

The identity member is a required part of the entity definition, it not only tells us what type represents the unique identifier for this entity but is also used in event sources (see section 2.7.3).

module example is

  entity Person is
  
    identity id -> PersonId

    emergency_contact (emergency_contact_for) -> {0..2} Person is
      @dc:description = "Emergency contact person"
    end
  
  end
end

Entity Events, or simply Events, model notifications generated by an entity most often representing a state change in the entity. As such a source reference denotes the entity which generates this event. Any expansion of the event structure must include the identifiers of the source entity.

EventDef
    ::= "event" Identifier
        "source" IdentifierReference
        StructuredBody?

module example is

  event PersonNameChanged source Person

end

With the expansion of the source entity the event definition above is logically equivalent to the following structure.

module example is

  structure PersonNameChanged is
    id -> PersonId is
      @sdml:identifies = Person
    end
  end

end

As we have seen before, the event PersonNameChanged in listing 30 is valid but incomplete.

The following is a valid and complete event definition with two structure members.

module example is

  event PersonNameChanged source Person is
    fromValue -> Name
    toValue -> Name
  end

end

An enumeration defines a set of unique constant values. The representation of these values is not defined by SDML, allowing users of the model to choose a scheme that matches their need.

Note that the keyword of and not is starts an enumeration body.

EnumDef
    ::= "enum" Identifier EnumBody?

module example is

  enum DistanceUnit

end

The enumeration DistanceUnit in 32 is valid but incomplete. Completion of the enumeration requires the addition of a body with enumeration variants.

EnumBody
    ::= "of" Annotation* ValueVariant+ "end"

ValueVariant
    ::= Identifier AnnotationOnlyBody?

The following demonstrates a valid and complete enumeration.

module example is

  enum DistanceUnit of
    Meter
    Foot
  end

end

While SDML only guarantees that a unique value is assigned to each variant within an enumeration it does not say what the type of this value is, or how it is represented. In effect the datatype of a variant’s value is opaque and therefore supports only equality tests.

Where it is useful to assign specific values to variants this can be accomplished with a pair of annotations, owl:equivalentClass and rdf:value. The first identifies a specific datatype to be used to represent the enumeration. Listing 34 shows our previous enum declaration with a representation type of sdml:integer, however the specific values for each variant are still assigned by the model. Only types derived from the types boolean, decimal, integer, iri, string or unsigned are allowed as enum representation types.

module example is

  import owl

  enum DistanceUnit of
    @owl:equivalentClass = sdml:integer
  
    Meter
    Foot
  end

end

It is possible for the model author to set specific values for each variant, if they have provided an equivalent class annotation to the declaration for the enum itself. To accomplish this, the author adds an rdf:value attribute property to each variant with a unique value with the datatype specified.

module example is

  import [ owl rdf ]

  enum DistanceUnit of
    @owl:equivalentClass = sdml:integer

    Meter is
      @rdf:value = 1
    end

    Foot is
      @rdf:value = 2
    end

  end

end

Specifically, to assign values to enumerations the following constraints must be met:

1. The value of an owl:equivalentClass annotation on an enum declaration must be one of the supported datatypes, or a type derived from one.
2. If more than one owl:equivalentClass annotation is present they must have distinct base data types. See listing 36.
3. The presence of an rdf:value annotation on a variant requires the presence of a corresponding owl:equivalentClass annotation on the enclosing enum declaration.
4. If no rdf:value is specified for a variant the model will assign a unique value.
   1. It is recommended that you either specify all values, or leave all to the model to assign.
5. Each variant’s rdf:value must be unique.
6. Where the literal syntax of a type overlaps, specifically for signed and unsigned integers, type constructors may be used to disambiguate the value type. See listing 37.

module example is

  import [ owl rdf ]

  enum DistanceUnit of
    @owl:equivalentClass = sdml:integer
    @owl:equivalentClass = sdml:string

    Meter is
      @rdf:value = 1
    end

    Foot is
      @rdf:value = 2
    
    end

  end

end

module example is

  import [ owl rdf ]

  enum DistanceUnit of
    @owl:equivalentClass = sdml:integer
    @owl:equivalentClass = sdml:unsigned

    Meter is
      @rdf:value = xsd:integer(1)
    end

    Foot is
      @rdf:value = xsd:integer(2)
    end

  end

end

A disjoint, or discriminated, union is a mechanism to allow for a selection of disjoint types to be treated as a single type. As such the variants of the union are simply type references, although they do allow annotations. Note also that the keyword of and not is starts a union body.

UnionDef
    ::= "union" Identifier UnionBody?

module example is

  union VehicleClass

end

The union VehicleClass in 38 is valid but incomplete. Completion of the union requires the addition of a body with type variants.

UnionBody
    ::= "of"
        Annotation* TypeVariant+
        "end"

TypeVariant
    ::= IdentifierReference TypeVariantRename? AnnotationOnlyBody?

TypeVariantRename
    ::= "as" Identifier

The following is a valid and complete example with three type variants and one that is renamed from Van to LittleTruck.

module example is

  union VehicleClass of
    Car
    Truck
    Van as LittleTruck
  end

end

To allow for the capture of member names before the elaboration of all types the language allows for the target type to be replaced with the keyword unknown. This marks the member, and by extension it’s owning type, as incomplete. Note the grammar allows ASCII and Unicode representations of the has type operator.

TypeExpressionTo
    ::= HasType Cardinality? "features"? TypeReference
HasType
    ::= "->" | "→"
TypeReference
    ::=  UnknownType | IdentifierReference | BuiltinSimpleType | MappingType
UnknownType
    ::= "unknown"

A mapping type denotes a functional relationship between the domain (left-hand type) and range (right-hand type).

MappingType
    ::= "(" TypeReference HasType TypeReference ")"

The syntax for mapping values was previously described in section 2.4.10.

The cardinality of a member is specified as a range operation with a minimum and maximum number of occurrences specified. Additionally cardinality constraints determine the ordering and uniqueness of the collection of member values in a sequence type (see section 2.5).

• The form {1..3} specifies a cardinality of 1 to 3 inclusive, or \([1,3]\) in interval notation.
• The form {1..} specifies a minimum of 1 occurrences an unbounded maximum, or \([1,\infty]\) in interval notation.
• The form {1} specifies that 1 is both the minimum and maximum value, or \([1,1]\) in interval notation, commonly termed a degenerate interval.

Cardinality
    ::= "{" SequenceOrdering? SequenceUniqueness? CardinalityInner "}"
CardinalityInner
    ::= Unsigned CardinalityRange?
CardinalityRange
    ::= ".." Unsigned?

SequenceOrdering
    ::= ( "ordered" | "unordered" )
SequenceUniqueness
    ::= ( "unique" | "nonunique" )

PropertyRef
    ::= "ref" IdentifierReference

In the following example (42) we see two members, default and name. The former is actually a reference to a property role, specifically the role default within the property definition AccountId in module account. The latter is a defined member with the name name and the type string and default cardinality.

module example is

  import accounts

  structure Record is
    ref accounts:accountId
    name -> string
  end

end

…

TypeExpressionTo
    ::= HasType Cardinality? "features"? TypeReference

module rentals is

  import vehicles

  entity Rental is
    identity id -> unknown
    options -> features vehicles:Options
  end

end

module rentals is

  import vehicles

  entity Rental is
    identity id -> unknown
    options -> vehicles:Options is
      assert is_exclusive_feature is
        forall self (
          self.type_of_type = sdml:Union and
          is_unique({ t | forall t in X, type_of(t) })
        )
      end
    end
  end

end

SimpleSentence
    ::= Atomic | Equation | Inequation

In the case of an atomic sentence the first term is the name of a predicate and the remaining terms are arguments to the predicate invocation.

Atomic
    ::= Term ActualArguments
ActualArguments
    ::= "(" Term* ")"

An equation asserts the equality of it’s left and right operand.

Equation
    ::= Term "=" Term

An inequation asserts the inequality of it’s left and right operand according to some relation.

Inequation
    ::= Term InequationRelation Term

The following are the recognized inequality relations, note the inclusion of both ASCII and Unicode versions of some relation symbols.

InequationRelation
    ::= ( '/=' | '≠' | '<' | '>' | '<=' | '≤' | '>=' | '≥' )

Boolean sentences allow for the logical composition of sentences.

BooleanSentence
    ::= UnaryBooleanSentence | BinaryBooleanSentence

UnaryBooleanSentence
    ::= NegationOperator ConstraintSentence
Negation
    ::= ( "not" | "¬" ) ConstraintSentence

BinaryBooleanSentence
    ::= ConstraintSentence LogicalConnective ConstraintSentence
LogicalConnective
    ::= ConjunctionOperator
        | DisjunctionOperator
        | ExclusiveDisjunctionOperator
        | ImplicationOperator
        | BiconditionalOperator

ConjunctionOperator
    ::= ( "and" | "∧" ) ConstraintSentence
DisjunctionOperator
    ::= ( "or" | "∨" ) ConstraintSentence
ExclusiveDisjunctionOperator
    ::= ( "xor" | "⊻" ) ConstraintSentence
ImplicationOperator
    ::= ( "implies" | "⇒" ) ConstraintSentence
BiconditionalOperator
    ::= ( "iff" | "⇔" ) ConstraintSentence

SDML supports, as shown in listing 54 sentences that range over values using the universal (\(\forall\)) or existential (\(\exists\)) quantifiers. A quantified sentence is therefore a sentence body with a set of variables bound to these quantified values.

QuantifiedSentence
    ::= QuantifiedVariableBinding+ ","? ConstraintSentence

Each variable binding specifies a quantifier, one or more names, and a source for variable values.

QuantifiedVariableBinding
    ::= ( UniversalQuantifier | ExistentialQuantifier ) QuantifiedVariable
UniversalQuantifier
    ::= "forall" | "∀"
ExistentialQuantifier
    ::= "exists" | "∃"

The special variable self is a shortcut for the set of values from the type of the element to which the constraint is attached.

QuantifiedVariable
    ::= ReservedSelf | Identifer MembershipOperator Term
MembershipOperator
    ::= ( "in" | "∈" )

Term
    ::= SequenceBuilder
        | FunctionalTerm
        | FunctionComposition
        | IdentifierReference
        | ReservedSelf
        | PredicateValue

FunctionalTerm
    ::= Term ActualArguments

FunctionComposition
    ::= ( "self" | Identifier ) ( "." Identifier )+

This notation is effectively syntactic sugar as it can be systematically transformed into the form above. The transformation rules are:

1. The reserved words self and Self may only appear as the first element.
2. The list of names after the first are reversed and applied in turn as functions.
   • name.suffix becomes suffix(name(_))
3. The first element will become the first argument to the inner-most function.
   • name.suffix becomes suffix(name(def))
4. If the path ends in an argument list the arguments are added to the corresponding function call.
   • suffix(name(def)) + ("Rental") becomes suffix(name(def) "Rental")

Similarly the quantifier collection self.definitions becomes definitions(self).

PredicateValue
    ::= SimpleValue | SequenceOfPredicateValues
SequenceOfPredicateValues
    ::= "∅"
        | SequenceValueConstraint?
          "[" ( SimpleValue | IdentifierReference )* "]"

Note that the keyword ∅ denotes the empty set, or an empty sequence [] that is unique. Note that, like a normal sequence of values, sequence constraints may be included.

ReservedSelf
    ::= "self"

A sequence builder uses set-builder notation to allow both specific selection of elements from sequences and values from types. A sequence builder expression describes a sequence as a selection of values from existing sequences filtered using predicates.

The simplest form of a builder expression is \(\bigl\{ x \mid P(x)\bigr\}\), where \(x\) is a variable and \(P\) is a predicate that evaluates to true to select the value of \(x\). In natural language this expression read as follows “construct a sequence of values of \(x\) such that the predicate \(f\) holds true for \(x\)”.

However, this simple form tells us nothing about the domain of the variable \(x\), and in fact \(x\) is a free variable in the expression because of this lack of binding. The expression \(\bigl\{ x \mid \forall x \in X, P(x)\bigr\}\) binds the variable \(x\) to the elements of the sequence, or the values of the type, named \(X\). SDML does not allow free variables in sequence builders and so variable bindings must be present for all specified variables.

SequenceBuilder
    ::= "{"
        ( NamedVariableSet | MappingVariable )
        "|"
        SequenceBuilderBody
        "}"

The variables returned to the caller are specified before the | character and may either be a list of identifiers or a single mapping of identifer to identifer.

NamedVariableSet
    ::= Identifier+
MappingVariable
    ::= "(" Identifier HasType Identifier ")"

With a named variables set the builder returns a single value and a set of relations named for the variable identifiers.

\[t ≔ \bigl\{ x, y \mid x \in X, y \in Y, P(x) \land Q(y) \land x = y \bigr\}\]

On the other hand, a mapping variable returns a sequence of mapping values which may comprise a lookup table.

\[t ≔ \bigl\{ \left(d \rightarrow r\right) \mid \forall d \in D, \exists r \in R, id_{D}(d) = id_{R}(r) \bigr\}\]

SequenceBuilderBody
    ::= QuantifiedSentence | "(" QuantifiedSentence ")"

A formal constraint may start with an environment that includes one or more definitions that are then used in the constraint body. A definition introduces a new function or constant – a constant is effectively a 0-arity function – although the function body may be a value or a constraint sentence and not specify side-effects.

ConstraintEnvironment
    ::= EnvironmentDef+ "in"

EnvironmentDef
    ::= "def" Identifier ( FunctionDef | ConstantDef )

A defined function has a signature that describes it’s domain, or parameters, and it’s range, or return type.

FunctionDef
    ::= FunctionSignature FunctionBody
FunctionSignature
    ::= ( "(" FunctionParameter+ ")" )? FunctionType
FunctionParameter
    ::= Identifier FunctionType

Function type specifications may use wildcard symbols to denote their application to undefined types.

FunctionType
    ::= HasType FunctionCardinality? FunctionTypeRef
FunctionCardinality
    ::= "{"
        SequenceOrdering? SequenceUniqueness? CardinalityInner?
        "}"
FunctionTypeRef
    ::= Optional? ( IdentiferReference | BuiltinSimpleType | MappingType )
Optional
    ::= "?"

FunctionBody
    ::= ByDefinition ConstraintSentence

ConstantDef
    ::= ByDefinition ( PredicateValue | ConstraintSentence )

The example in listing 56 is an expansion of the informal example in listing 50. Here we check for the presence of the annotation on every top-level definition and then any members of that definition. Note that this example also demonstrates the ability to create new predicates as in has_pref_label which simplifies the body of the constraint.

module labelled is

  assert must_have_preferred_label is
    def has_pref_label(anns → {0..} Annotation) ≔
      ∃ a ∈ anns ( a.name = skos:prefLabel ∧ ¬a.value.is_empty )
  in
    has_pref_label(self.annotations)
    ∧ ∀ d ∈ self.definitions (
      has_pref_label(d.annotations)
      ∧ Entity(d) ⇒ ∀ m ∈ d.flat_members ( has_pref_label(m.annotations) )
      ∧ Enumeration(d) ⇒ ∀ m ∈ d.variants ( has_pref_label(m.annotations) )
      ∧ Event(d) ⇒ ∀ m ∈ d.flat_members ( has_pref_label(m.annotations) )
      ∧ Structure(d) ⇒ ∀ m ∈ d.flat_members ( has_pref_label(m.annotations) )
      ∧ Union(d) ⇒ ∀ m ∈ d.variants ( has_pref_label(m.annotations) )
      ∧ Property(d) ⇒ ∀ m ∈ d.roles ( has_pref_label(m.annotations) )
    )
  end

end

The introduction of optional types, that it a type name preceded by the operator “?” may be considered a convenience over the same type specified with a cardinality of {0..1}. However, this greatly simplifies the implementation of constraints over possibly missing values.

def predicate(Type) -> boolean
def predicate(value -> Type) -> boolean

def relation(Type1, Type2) -> boolean
def relation(value1 -> Type1, value2 -> Type2) -> boolean

def function(Type, ...) -> RType
def function(value -> Type, ...) -> RType

$ sdlml highlight --help
Highlight an SDML source file

Usage: sdml highlight [OPTIONS] [MODULE]

Arguments:
  [MODULE]
          SDML module, loaded using the standard resolver

Options:
  -f, --output-format <OUTPUT_FORMAT>
          Format to convert into
          
          [default: ansi]

          Possible values:
          - ansi:            ANSI escape for console
          - html:            HTML pre-formatted element
          - html-standalone: HTML stand-alone document

  -v, --verbose...
          More output per occurrence

  -o, --output-file <OUTPUT_FILE>
          File name to write to, if not provided will write to stdout

  -q, --quiet...
          Less output per occurrence

  -b, --base-path <BASE_PATH>
          A path to pre-pend to the resolver search path

  -i, --input-file <INPUT_FILE>
          SDML File name, load without resolver

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

For the console this uses ANSI escape sequences to format the text.

$ sdml highlight --output-format ansi rentals

To generate formatted and highlighted HTML the tool accepts two different format specifiers, html for simply a block of HTML that can be inserted into another document, or html-standalone to generate a full document around the highlighted code block.

$ sdml highlight --output-format html rentals
$ sdml highlight --output-format html-standalone rentals

To draw a high-level Concepts diagram, use the diagram specifier concepts. To generate an image file you need to install Graphviz³⁰.

$ sdml draw --diagram concepts \
            --output-format svg --output-file rentals.svg \
            --base-path . rentals

For more detail an Entity-Relationship diagram can be generated with the diagram specifier entity-relationship. To generate an image file you need to install Graphviz³⁰.

$ sdml draw --diagram entity-relationship \
            --output-format svg --output-file rentals.svg \
            --base-path . rentals

For the mose detail a UML Class diagram can be generated with the diagram specifier uml-class. The generated diagram applies the profile outlined in appendix 13. To generate an image file you need to install PlantUML³¹.

$ sdml draw --diagram uml-class \
            --output-format svg --output-file rentals.svg \
            --base-path . rentals

A particular module rentals is resolved by looking for the module name first with the “.sdm” and then the “.sdml” extension. If neither of these exist the same pair will be checked within a directory named rentals. So in total the following four file paths are checked.

{prefix}rentals.sdm
{prefix}rentals.sdml
{prefix}rentals/rentals.sdm
{prefix}rentals/rentals.sdml

The purpose of the variable {prefix} is to allow the resolver to use an environment variable, SDML_PATH, to find and load module files. Each path within the variable is used as a prefix in turn. The command line option base-path allows you to prepend a value to the SDML_PATH list for just this command. In the following example:

SDML_PATH=lib/sdml sdml highlight --base-path ./examples rentals

The list of file paths to check are:

lib/sdml/rentals.sdm
lib/sdml/rentals.sdml
lib/sdml/rentals/rentals.sdm
lib/sdml/rentals/rentals.sdml
./examples/rentals.sdm
./examples/rentals.sdml
./examples/rentals/rentals.sdm
./examples/rentals/rentals.sdml

This same resolution mechanism is used for all imported values, in the following example each module skos, other, and more. With one exception, the module skos is known to the sdml command and it uses an internal representation.

module subDomain is

  import skos:prefLabel
  import other:Something
  import more

end

Syntax highlighting is enabled by the tree-sitter-hl-mode minor mode based on the configuration in the constant sdml-mode-tree-sitter-hl-patterns. The highlighting (figure 17) also carries over into Org Babel source blocks and into generated content such as this documentation.

The sdml-mode also adds to the prettify-symbols-alist list, the set of symbols is in the custom variable sdml-prettify-symbols-alist.

Line indentation is enabled by the tree-sitter-indent-mode minor mode based on the configuration in the constant sdml-mode-folding-definitions.

Default indentation is two spaces, although this can be overridden by the custom variable sdml-indent-offset.

Block Folding is provided by the ts-fold-mode minor mode based on the configuration in the constant tree-sitter-indent-sdml-scopes. Note that folding of groups of line comments is also supported.

• C-c C-s - – fold item
• C-c C-s + – unfold item
• C-c C-s C-- – fold all items in buffer
• C-c C-s C-+ – unfold all items in buffer
• C-c C-s / – unfold item and all children
• C-c C-s . – toggle fold/unfold state

As well as the mechanics of folding, the ts-fold package also has indicator support for windowed clients and this is enabled by default with window-system is non-nil.

This package provides a number of useful abbreviations/skeletons to help editing. The built-in abbrev-mode is enabled by sdml-mode and when typing one of the abbreviations below use a space to expand. For example, typing d t SPC will prompt for a name and expand into the SDML declaration where the underscore character represents the new cursor position. A number of abbreviations will ask for values, check the minibuffer. A complete list of abbreviations set by sdml-mode is shown in table 9.

  datatype MyName ← opaque _

Where an abbreviation expands a property whose value is a language string the current value of the Emacs variable locale-language is included as the string language.

The following two comands are provided by the underlying tree-sitter package, but exposed here with the common key prefix.

• C-c C-s d – open the tree-sitter debug view
• C-c C-s q – open the tree-sitter query builder

The additional package sdml-ispell provides selective spell checking by only checking selected nodes in the tree.

• C-c C-s s – spell check the item at point
• C-c C-s C-s – spell check all items in the buffer

By default only strings and comments will be checked, although this can be overridden by the custom variable tree-sitter-ispell-sdml-text-mapping.

The additional package flycheck-sdml provides on-the-fly linting for SDML buffers. To enable, simply ensure Flycheck mode is enabled for your buffer. Rather than per-buffer, you can enable this by setting flycheck-mode for all SDML files with a hook. Figure 17 shows the flycheck buffer open with advice provided and a fringe indicator for the reported issue.

The entire set of lint rules are stored in the custom variable sdml-lint-rules with the form:

'(rule-id "Issue message" level "tree-sitter query")

For example, the following rule returns the name of the module, but only if the first character is an upper case letter. This is marked as a warning by Flycheck and provided with the necessary message.

'(module-name-case
  "Module names may not start with upper-case"
  warning
  "((module name: (identifier) @name) (#match? @name \"^[:upper:]\"))")

Org-Babel support provides the ability to call the SDML command-line tool to produce diagrams and more. For example, the following source block calls the CLI to draw a concept diagram for the enclosed module. It is worth noting that this documentation has been generated, including all source highlighting and diagrams, from an Org-mode document with Babel.

#+NAME: lst:rentals-example
#+CAPTION: Rentals Concepts
#+BEGIN_SRC sdml :cmdline draw --diagram concepts :file ./rentals-concepts.svg :exports both
module rentals is

  entity Vehicle
  entity Location
  entity Customer
  entity Booking

end
#+END_SRC

The results block then references the resulting image.

#+NAME: fig:rentals-example-concepts
#+CAPTION: Rentals Concepts
#+RESULTS: lst:rentals-example
[[file:./rentals-concepts.svg]]

Figure 18 shows this experience in Emacs, note that each SRC block has language-specific syntax highlighting. Emacs provides a command, org-edit-special, which opens the block in it’s own buffer for editing with all the capabilities of a file-backed resource.

But, what if we want to produce more than one diagram from the same source? By using the built-in noweb syntax we can create a new source block, but reference the original content. This source block has different command-line parameters and has it’s own results block as well.

#+NAME: fig:rentals-example-erd
#+BEGIN_SRC sdml :cmdline draw --diagram concepts :file ./rentals-erd.svg :exports results :noweb yes
<<lst:rentals-example>>
#+END_SRC

TextMate is another popular editor, and it’s in-built language descriptions have been adopted by other tools as a semi-standard mechanism for providing syntax highlighting. The SDML TextMate bundle includes a grammar file as well as a set of snippets for easy addition of language features in source files.

Figure 24 shows the bundle menu for SDML with the list of declaration snippets.

Figure 24 shows the bundle menu for SDML with the list of annotation property snippets.

Additionally, every TextMate window has an integrated Symbol List in the footer to easily navigate around a large file. SDML includes every type declaration as a symbol in the list with their corresponding members or variants shown indented as seen in figure 26.

The installer script (section 6.1) performs the following steps if you select TextMate as your editor:

1. Install the editor using brew.
2. Clone the language bundle into the editor’s bundle folder.
3. Have TextMate reload all bundles (on macos only).

The installer script (section 6.1) performs the following steps if you select Sublime Text as your editor:

1. Install the editor using brew.
2. Clone the language bundle into the editor’s bundle folder.

IntelliJ IDEA, and by extension most of the JetBrains tools, has a native plugin that acts as a bridge to use TextMate bundles as-is.

To enable this plugin go to the IDE settings and select the Plugins section and the Installed tab. Find the bundle named “TextMate Bundles” and set the checkbox next to it to enable. Click the Apply button to save the changes and close the dialog. Restart the IDE if prompted.

To add the SDML bundle either download the bundle from https://github.com/sdm-lang/SDML.tmbundle, or use Git to clone onto your local file system. Go to the IDE settings and select the Editor section and TextMate Bundles sub-section. Click the + at the top of the list and locate the bundle you downloaded. You should see it now in the list of bundles and you can enable/disable it with the checkbox next to it.

Opening SDML files should now provide syntax highlighting.

The installer script (section 6.1) performs the following steps if you select IDEA as your editor:

1. install the editor using brew.
2. Point the user to next-step instructions.

Neovim has some great tree-sitter support with the nvim-tree-sitter and a nice in-editor playground. Firstly, add the tree-sitter plugin, but don’t install yet, as shown on the nvim-treesitter page (using vim-plug):

call plug#begin()
Plug 'nvim-treesitter/nvim-treesitter', {'do': ':TSUpdate'}
call plug#end()

Now, add the following Lua block, using content from the homepage, and then set the ensure_installed to include the query language and so highlight tree-sitter queries and set ignore_install to include sdml before installing the tree-sitter plugin. The builtin sdml grammar will unfortunately install queries that will then be a problem so we want to avoid that.

require'nvim-treesitter.configs'.setup {
    ensure_installed = { "query" }, 
    sync_install = false,
    auto_install = true,
    highlight = {
        enable = true,
        disable = {},
        additional_vim_regex_highlighting = false,
    },
    incremental_selection = {
        enable = true,
        keymaps = {
            init_selection = "gnn",
            node_incremental = "grn",
            scope_incremental = "grc",
            node_decremental = "grm",
        },
    },
    indent = {
        enable = true
    },
    query_linter = {
        enable = true,
        use_virtual_text = true,
        lint_events = {"BufWrite", "CursorHold"},
    },
}

To allow tree-sitter to do folding based on folds.scm, add the following to init.vim.

set foldmethod=expr
set foldexpr=nvim_treesitter#foldexpr()

Once the core plugin has been installed you can add the following Lua block in init.vim to install this grammar.

local parser_config = require "nvim-treesitter.parsers".get_parser_configs()

parser_config.sdml = {
    install_info = {
        url = "https://github.com/sdm-lang/tree-sitter-sdml",
        files = {"src/parser.c"},
        generate_requires_npm = true, 
        requires_generate_from_grammar = true,  
    },
    filetype = "sdm",
    maintainers = { "@johnstonskj" },
}

Additionally, try the nvim-treesitter-context and nvim-treesitter-refactor plugins based on tree-sitter.

call plug#begin()

Plug 'nvim-treesitter/nvim-treesitter', {'do': ':TSUpdate'}
Plug 'nvim-treesitter/nvim-treesitter-context' 
Plug 'nvim-treesitter/playground'

call plug#end()

Add the corresponding configuration:

require'nvim-treesitter.configs'.setup {
    // …
    playground = {
        enable = true,
        disable = {},
        updatetime = 25,
        persist_queries = false,
        keybindings = {
            toggle_query_editor = 'o',
            toggle_hl_groups = 'i',
            toggle_injected_languages = 't',
            toggle_anonymous_nodes = 'a',
            toggle_language_display = 'I',
            focus_language = 'f',
            unfocus_language = 'F',
            update = 'R',
            goto_node = '<cr>',
            show_help = '?',
        },
    }
}

The installer script (section 6.1) performs the following steps if you select Neovim as your editor:

1. install the editor using brew.
2. Point the user to next-step instructions.

As module files most likely exist as part of a larger project, or may be organized into folders, it is useful to be able to put the catalog file in the root of a project. Therefore, the resolver, if not provided an explicit location, will look in the current working directory, and then it’s parent directory and so on until either a catalog file is found or we reach the file-system root.

..
  /parent
    /project
      /src
        vehicle-v1.sdm
      sdml-catalog.json

More TBD.

The example in listing 63 shows how to map the module identifier vehicle to a file and a base URL. The root of the catalog has a mapping named entries which has identifiers as keys and either groups or items as values. The item only has two properties, a relative URL and a relative file-system path.

{
  "base": "https://example.org/rentals/",
  "entries": {
    "vehicle": {
      "item": {
        "relative_uri": "vehicle#",
        "relative_path": "src/vehicle-v1.sdm"
      }
    }
  }
}

The relative path in an item is added to the directory in which the catalog was located, not relative to where the resolver is executed. For example, if the resolver is executed in the project directory the path to the catalog is ./sdml-catalog.json. Removing the file name gives the path . to which we add the relative path from the matching item to result in ./src/vehicle-v1.sdm.

Using the example from the previous section, if the resulting ./src/vehicle-v1.json file contains a base attribute it will take precedent. If no base attribute is present, a URL will be constructed by resolving the relative URL from the item against the base URL specified in the catalog root. In the case of our example this becomes:

<https://example.org/rentals/> + "vehicle#" = <https://example.org/rentals/vehicle#>

When a project becomes more complex it is useful to provide organization in the form of folder structures.

More TBD

..
  /parent
    /project
      /src
        /inventory
          vehicle-v1.sdm
        /customer
          commercial-v2.sdm
          customer-v2.sdm
          retail-v3.sdm
      sdml-catalog.json

More TBD

{
  "base": "https://example.org/rentals/",
  "entries": {
    "inventory": {
      "group": {
        "relative_path": "src/inventory/",
        "entries": {
          "vehicle": {
            "item": {
              "relative_uri": "vehicle#",
              "relative_path": "vehicle-v1.sdm"              
            }
          }
        }
      }
    },
    "customer": {
      "group": {
        "relative_path": "src/customer/",
        "entries": {
          "commercial": {
            "item": {
              "relative_uri": "commercial#",
              "relative_path": "commercial-v2.sdm"              
            }
          },
          "customer": {
            "item": {
              "relative_uri": "customer#",
              "relative_path": "customer-v2.sdm"              
            }
          }
          "retail": {
            "item": {
              "relative_uri": "retail#",
              "relative_path": "retail-v3.sdm"              
            }
          }
        }
      }
    }
  }
}

This means that the path for the module vehicle = . + src/inventory/ + vehicle-v1.sdm and the path for the module customer = . + src/customer/ + customer-v2.sdm.

This module

module dc base <http://purl.org/dc/elements/1.1/> is
  structure contributor ;; ...
  structure coverage ;; ...
  structure creator ;; ...
  structure date ;; ...
  structure description ;; ...
  structure format ;; ...
  structure identifier ;; ...
  structure language ;; ...
  structure publisher ;; ...
  structure relation ;; ...
  structure rights ;; ...
  structure source ;; ...
  structure subject ;; ...
  structure title ;; ...
  structure type ;; ...
end

This module

module dc_am base <http://purl.org/dc/dcam/> is
  structure VocabularyEncodingScheme ;; ...
  structure domainIncludes ;; ...
  structure memberOf ;; ...
  structure rangeIncludes ;; ...
end

This module

module dc_type base <http://purl.org/dc/dcmitype/> is
 structure Collection ;; ...
  structure Dataset ;; ...
  structure Event ;; ...
  structure Image ;; ...
  structure InteractiveResource ;; ...
  structure MovingImage ;; ...
  structure PhysicalObject ;; ...
  structure Service ;; ...
  structure Software ;; ...
  structure Sound ;; ...
  structure StillImage ;; ...
  structure Text ;; ...
end

This module

module dc_terms base <http://purl.org/dc/terms/> is
  structure Agent ;; ...
  structure AgentClass ;; ...
  structure BibliographicResource ;; ...
  structure Box ;; ...
  structure DCMIType ;; ...
  structure DDC ;; ...
  structure FileFormat ;; ...
  structure Frequency ;; ...
  structure IMT ;; ...
  structure ISO3166 ;; ...
  structure ISO639_2 ;; ...
  structure ISO639_3 ;; ...
  structure Jurisdiction ;; ...
  structure LLC ;; ...
  structure LCSH ;; ...
  structure LicenseDocument ;; ...
  structure LinguisticSystem ;; ...
  structure Location ;; ...
  structure LocationPeriodOrJurisdiction ;; ...
  structure MESH ;; ...
  structure MediaType ;; ...
  structure MediaTypeOrExtent ;; ...
  structure MethodOfAccrual ;; ...
  structure MethodOfInstruction ;; ...
  structure NLM ;; ...
  structure Period ;; ...
  structure PeriodOfTime ;; ...
  structure PhysicalMedium ;; ...
  structure PhysicalResource ;; ...
  structure Point ;; ...
  structure Policy ;; ...
  structure ProvenanceStatement ;; ...
  structure RFC1766 ;; ...
  structure RFC3066 ;; ...
  structure RFC4646 ;; ...
  structure RFC5646 ;; ...
  structure RightsStatement ;; ...
  structure SizeOrDuration ;; ...
  structure Standard ;; ...
  structure TGN ;; ...
  structure UDC ;; ...
  structure URI ;; ...
  structure WthreeCDTF ;; ...
  structure abstract ;; ...
  structure accessRights ;; ...
  structure accrualMethod ;; ...
  structure accrualPeriodicity ;; ...
  structure accrualPolicy ;; ...
  structure alternative ;; ...
  structure audience ;; ...
  structure available ;; ...
  structure bibliographicCitation ;; ...
  structure conformsTo ;; ...
  structure contributor ;; ...
  structure coverage ;; ...
  structure created ;; ...
  structure creator ;; ...
  structure date ;; ...
  structure dateCopyrighted ;; ...
  structure dateSubmitted ;; ...
  structure description ;; ...
  structure educationLevel ;; ...
  structure extent ;; ...
  structure forma ;; ...
  structure hasFormat ;; ...
  structure hasPart ;; ...
  structure hasVersion ;; ...
  structure identifier ;; ...
  structure instructionalMethod ;; ...
  structure isFormatOf ;; ...
  structure isPartOf ;; ...
  structure isReferencedBy ;; ...
  structure isReplacedBy ;; ...
  structure isRequiredBy ;; ...
  structure isVersionOf ;; ...
  structure issued ;; ...
  structure language ;; ...
  structure license ;; ...
  structure mediator ;; ...
  structure medium ;; ...
  structure modified ;; ...
  structure provenance ;; ...
  structure publisher ;; ...
  structure references ;; ...
  structure relation ;; ...
  structure replaces ;; ...
  structure requires ;; ...
  structure rights ;; ...
  structure rightsHolder ;; ...
  structure source ;; ...
  structure spatial ;; ...
  structure subject ;; ...
  structure tableOfContents ;; ...
  structure temporal ;; ...
  structure title ;; ...
  structure type ;; ...
  structure valid ;; ...
end

This module

module owl base <http://www.w3.org/2002/07/owl#> is end

This module

module rdf base <http://www.w3.org/1999/02/22-rdf-syntax-ns#> is
  structure Alt ;; ...
  structure Bag ;; ...
  structure CompoundLiteral ;; ...
  structure HTML  ;; ...
  structure JSON ;; ...
  structure List ;; ...
  structure PlainLiteral ;; ...
  structure Property ;; ...
  structure Seq ;; ...
  structure Statement ;; ...
  structure XMLLiteral ;; ...
  structure direction
  structure first ;; ...
  structure langString ;; ...
  structure language ;; ...
  structure nil ;; ...
  structure object ;; ...
  structure predicate ;; ...
  structure rest ;; ...
  structure subject ;; ...
  structure type ;; ...
  structure value ;; ...
end

This module

module rdf_schema base <http://www.w3.org/2000/01/rdf-schema#> is
  structure Class ;; ...
  structure Container ;; ...
  structure ContainerMembershipProperty  ;; ...
  structure Datatype ;; ...
  structure Literal ;; ...
  structure Resource ;; ...
  structure comment ;; ...
  structure domain ;; ...
  structure isDefinedBy ;; ...
  structure label ;; ...
  structure member ;; ...
  structure range ;; ...
  structure seeAlso ;; ...
  structure subClassOf ;; ...
  structure subPropertyOf ;; ...
end

This module

module skos base <http://www.w3.org/2004/02/skos/core#> is
  structure Collection  ;; ...
  structure Concept ;; ...
  structure ConceptScheme ;; ...
  structure OrderedCollection ;; ...
  structure altLabel ;; ...
  structure broadMatch ;; ...
  structure broader ;; ...
  structure broaderTransitive ;; ...
  structure changeNote ;; ...
  structure closeMatch ;; ...
  structure definition ;; ...
  structure editorialNote ;; ...
  structure exactMatch ;; ...
  structure example ;; ...
  structure hasTopConcept ;; ...
  structure hiddenLabel ;; ...
  structure historyNote ;; ...
  structure inScheme ;; ...
  structure mappingRelation ;; ...
  structure member ;; ...
  structure memberList ;; ...
  structure narrowMatch ;; ...
  structure narrower ;; ...
  structure narrowerTransitive ;; ...
  structure notation ;; ...
  structure note ;; ...
  structure prefLabel ;; ...
  structure related ;; ...
  structure relatedMatch ;; ...
  structure scopeNote ;; ...
  structure semanticRelation ;; ...
  structure topConceptOf ;; ...
end