JSON Schema

(since v2.10.0)

1. Overview

This target derives a JSON Schema representation from an application schema in UML.

Note

A number of configuration options and extensions have been implemented. They are documented in detail in the OGC UGAS-2020 Engineering Report. Another source of information is the UML to JSON Encoding Rules specification. The documents also explain which model transformations may need to be applied before executing this target, for example to transform association classes. Therefore, if you are looking for a complete introduction of the conversion from UML to JSON Schema, read the according chapter in the OGC Engineering Report as well as the other specification first. This page provides a quick reference of the available conversion rules, parameters, and configuration elements.

2. Configuration

2.1. Class

The class for the Target implementation is de.interactive_instruments.ShapeChange.Target.JSON.JsonSchemaTarget.

2.2. Conversion Rules

The behavior for processing a model is primarily controlled through conversion rules. In addition, parameters and other configuration elements (like map entries) influence the way a schema is processed. An encoding rule represents a specific set of conversion rules.

An encoding rule is defined by an <EncodingRule> element.

Example:


  1
2
3
4
5
6
7

  <EncodingRule name="myGeoJson" extends="defaultGeoJson">
 <rule name="rule-json-cls-basictype"/>
 <rule name="rule-json-cls-codelist-uri-format"/>
 <rule name="rule-json-cls-name-as-entityType"/>
 <rule name="rule-json-cls-union-propertyCount"/>
 <rule name="rule-json-cls-valueTypeOptions"/>
</EncodingRule>

The name attribute of the <EncodingRule> element defines the identifier of the encoding rule to be used in the defaultEncodingRule parameter.

Note	The encoding rules 'defaultGeoJson' and 'defaultPlainJson' are pre-configured in ShapeChange. They can thus be used as-is, without the need to explicitly define them in the configuration. They can also be extended as required (see the example).

The optional extends attribute of the <EncodingRule> element includes all rules from the referenced encoding rule in this encoding rule, too.

Each <rule> references either a conversion rule or - possibly in the future - a requirement or recommendation to be tested before the conversion process.

This target supports the rules defined in the following subsections.

2.2.1. rule-json-all-documentation

(since v2.14.0)

With rule-json-all-documentation, descriptive information of application schema elements (packages, classes, and properties) can be encoded via JSON Schema annotations.

Note

Annotations represent one category of JSON Schema keywords. Annotations attach information that applications may use as they see fit. The other categories are assertions, which validate that a JSON instance satisfies constraints, and applicators, which apply subschemas to parts of the instance and combine their results.

Descriptive information of a model element in ShapeChange, i.e., properties (attributes and association roles), classes, and packages, includes the pieces of information, called descriptors, that are documented in Table 1.

Note	A model element can have all, a subset, or none of these descriptors.

Table 1. Well-known descriptors

Descriptor Name
(and ID)

Explanation

Name
(name)

The name of the model element (as named in the source UML, i.e., using upper and lower camel case).

Alias
(alias)

An alternative, human-readable name for the model element.

Definition
(definition)

The normative specification of the model element.

Description
(description)

Additional information about the model element.

Documentation
(documentation)

The overall documentation of the model element. May be structured, containing other descriptors (such as definition and description).

Example(s)
(example)

Example(s) illustrating the model element.

Global identifier
(globalIdentifier)

The globally unique identifier of the model element; that is, unique across models.

Legal basis
(legalBasis)

The legal basis for the model element.

Data capture statement(s)
(dataCaptureStatement)

Statement(s) describing how to capture instances of this model element from the real world.

Primary code
(primaryCode)

The primary code for this model element.

Note	The main code for a model element should be assigned to this descriptor. The primary code may be the only one. Optional additional tagged values may be added for other codes.

Note	The descriptor ID is used in ShapeChange configuration elements that define JSON Schema annotations.

Typically, a community has a preferred way to model and encode this information. For example, one community may want to encode the description of a model element via the "description" annotation, while another may prefer to encode the values of multiple descriptors of a model element within a single "description" annotation.

ShapeChange can support this type of diversity through JSON Schema annotation elements. An annotation element specifies how the content of a specific JSON Schema annotation (that shall be generated while converting a model element) shall be constructed. The annotation element takes into account that a UML model element may not have an actual value for a descriptor, and that some descriptors can have multiple values, e.g., the descriptor example.

In addition to the well-known descriptors (see previous table), additional descriptive information can be incorporated through UML tagged values from the application schema.

For details about configuring JSON Schema annotation elements, see JSON Schema Annotations.

2.2.2. rule-json-all-featureRefs

(since v2.14.0)

This conversion rule overrides the default behavior of ShapeChange when encoding property values by reference. The rule is meant to support the encoding of feature references as proposed for OGC API - Features - Part 5: Schemas.

Note	The proposal for OGC API - Features - Part 5: Schemas is subject to change, and thus the conversion rule, as implemented, may not fully reflect what is defined by that specification.

The conversion rule supports the following profiles, which define how a feature reference is encoded in actual JSON data:

rel-as-link - The feature reference is encoded as a link object. ShapeChange automatically creates an SCLinkObject definition in every generated JSON Schema where such a feature reference is used. The definition only requires the "href" member to be present in actual JSON data.
rel-as-uri - Encodes a feature reference as a simple string, with the format being defined by target parameter byReferenceFormat.
rel-as-key - Encodes feature references with plain feature identifier, possibly adding information about the collection id and a title.

The profile(s) to use are configured via target parameter featureRefProfiles.

Feature reference schema definitions for profile rel-as-key are constructed as follows:

First, ShapeChange determines if the feature reference is for an external collection. This is indicated either via map entry Parameter: collectionInfos, for cases in which the value type of a property is mapped, or via tagged value collectionUriTemplate (defined on the property value type). If a URI template is available, ShapeChange creates a JSON Schema definition for an external feature reference.
ShapeChange then determines the collection ids applicable for the property value type, i.e., the referenced feature type. If the type is mapped, collection infos must be defined by the map entry. If these infos are missing, the by reference encoding will be omitted (with a suitable error message in the log). The collection infos define the collection ids via characteristic collectionIds. If the type is not mapped, the collection ids are given by the names of all non-abstract classes that are in the subtype hierarchy of the type (including the type itself), with these names being converted to lower case. Note that in the future, additional methods for determining the collection ids can be designed and implemented.
The type(s) of feature identifiers in these collections must also be determined. For a mapped type, the identifier types are defined by map entry characteristic collectionIdTypes. For all other cases, the applicable identifier types are defined by target parameter featureRefIdTypes.
With all this information available, ShapeChange can create the right schema definition for a feature reference (all such definitions include member "x-ogc-role": "reference"; examples are shown below):
- If a URI template is available:
  - If the template does not contain variable {collectionId}, then a schema for a simple external reference is created. The schema contains a type definition with the determined feature identifier types. The schema also contains the "x-ogc-uriTemplate" member, with the template as value.
  - Otherwise, i.e. the template does contain variable {collectionId}, then a more complex external reference schema is created, defining a JSON object with required "collectionId" member (whose values are restricted if one or more collection ids have been determined before), required "featureId" member (whose type definition contains the determined feature identifier types), and an optional "title" member (of type string). The schema will also contain the "x-ogc-uriTemplate" member, with the template as value.
- Otherwise, i.e. no URI template is available:
  - If a single collection id was determined, and target parameter featureRefWithAnyCollectionId is not set to true, then a schema for a simple feature reference is created. The schema contains a type definition with the determined feature identifier types. It also contains the "x-ogc-collectionId" member, with the determined collection id as value.
  - Otherwise, a more complex reference schema is created, defining a JSON object with required "collectionId" member (whose values are restricted if target parameter featureRefWithAnyCollectionId is not set to true, and one or more collection ids have been determined before), required "featureId" member (whose type definition contains the determined feature identifier types), and an optional "title" member (of type string).

Examples

Simple reference schema:

{
  "type": "integer",
  "x-ogc-role": "reference",
  "x-ogc-collectionId": "buildings"
}

Simple external reference schema:

{
  "type": "string",
  "x-ogc-role": "reference",
  "x-ogc-uriTemplate": "https://example.com/foo/bar/{featureId}"
}

Reference schema:

{
  "type": "object",
  "x-ogc-role": "reference",
  "required": [
    "collectionId",
    "featureId"
  ],
  "properties": {
    "collectionId": {
      "type": "string",
      "enum": [
        "roads",
        "railways",
        "waterways"
      ]
    },
    "featureId": {
      "type": [
        "integer",
        "string"
      ]
    },
    "title": {
      "type": "string"
    }
  }
}

External reference schema:

{
  "type": "object",
  "x-ogc-role": "reference",
  "x-ogc-uriTemplate": "https://example.com/foo/{collectionId}/bar/{featureId}",
  "required": [
    "collectionId",
    "featureId"
  ],
  "properties": {
    "collectionId": {
      "type": "string"
    },
    "featureId": {
      "type": "integer"
    },
    "title": {
      "type": "string"
    }
  }
}

2.2.3. rule-json-all-notEncoded

This conversion rule suppresses the conversion to JSON Schema of any model elements (more specifically: application schemas, classes, and properties) for which the "jsonEncodingRule" tag is set to "notEncoded".

Note	The encoding rule "notEncoded" is defined in the standard rules, which can be included in the target configuration via:

<xi:include href="https://shapechange.net/resources/config/StandardRules.xml" />

2.2.4. rule-json-cls-basictype

If a direct or indirect supertype of an application schema class is mapped to one of the simple JSON Schema types string, number, integer, or boolean, then under rule-json-cls-basictype that class represents a so called basic type.

Note	Uses of the stereotype «BasicType» with application schema classes are ignored by this conversion rule.

A basic type does not define a JSON object. It represents a simple data value, e.g. a string. The JSON Schema definition of a basic type thus defines a simple JSON Schema type. A basic type can be restricted using a number of JSON Schema keywords. The following table defines which tagged values can be used to define these restrictions for a basic type, and which restrictions are available for which simple JSON Schema type.

JSON Schema keyword	tagged value to define the restriction	applicable JSON Schema type(s)
format	jsonFormat	string, number, integer
maxLength	length, maxLength, or size	string
minLength	minLength	string
pattern	jsonPattern	string
minimum (inclusive)	rangeMinimum or minInclusive	number, integer
exclusiveMinimum	minExclusive	number, integer
maximum (inclusive)	rangeMaximum or maxInclusive	number, integer
exclusiveMaximum	maxExclusive	number, integer

JSON Schema keyword

tagged value to define the restriction

applicable JSON Schema type(s)

format

jsonFormat

string, number, integer

maxLength

length, maxLength, or size

string

minLength

minLength

string

pattern

jsonPattern

string

minimum
(inclusive)

rangeMinimum or minInclusive

number, integer

exclusiveMinimum

minExclusive

number, integer

maximum
(inclusive)

rangeMaximum or maxInclusive

number, integer

exclusiveMaximum

maxExclusive

number, integer

2.2.5. rule-json-cls-codelist-link

This rule results in the conversion of a code list as a reference to the JSON Schema defining a link object. That reference must explicitly be configured using the target parameter linkObjectUri.

2.2.6. rule-json-cls-codelist-uri-format

With this rule, all code lists are represented by a JSON Schema that restricts the type to "string", and states that the "format" is "uri" (as defined by JSON Schema validation, section 7.3.5).

2.2.7. rule-json-cls-collectionsBasedOnEntityType

(since v2.14.0)

This rule creates collection schemas for feature types.

Note	Object types are ignored. Such types can be transformed to feature types (using the TypeConverter rule-trf-objectTypesToFeatureTypes), if they should be treated like feature types in the JSON encoding.

Caution

It is assumed that the content model of all relevant feature types contains an entity type member (e.g., "featureType", "type", "properties/type"), which identifies the name of the type of the encoded object. If no such entity type member is available for one of the feature types of a collection definition, ShapeChange will log an error and ignore that feature type when creating the collection definition. The collection definition is not created if all of the feature types are ignored.

Note

The entity type member can be defined via a MapEntry for one of the supertypes for a class, via target parameter baseJsonSchemaDefinitionForFeatureTypes_encodingInfos, or generated via rule-json-cls-name-as-entityType.
The collection encoding supports objects with different entity type member paths.
Via rule-json-cls-collectionsWithTopLevelEntityType, the conversion can be altered to support cases in which the entity type member is not set per object, but on the collection level for all objects. Of course, this only makes sense if all objects in a collection are of the same type.

The rule creates the following collection schema definitions:

A general "FeatureCollection" schema for all non-abstract feature types.
One collection schema for each feature type (abstract and non-abstract). Each of these schemas defines a uniform collection, i.e. a collection that only has objects of a specific feature type (or subtypes thereof). The collection name is {feature type name} + 'Collection'. Example: BuildingCollection.

Note	The generation of the uniform collections can be suppressed using target parameter featureCollectionOnly.

The JSON Schema files to which the collection definitions are added are determined as follows:

By default, the FeatureCollection schema will be added to the JSON Schema document that is created for the main schema package (for further details, see the description of input parameter mainAppSchema). The other collection schemas will be added to the JSON Schema documents that contain the definition of the respective feature type. If only a single application schema is processed, and all classes are encoded in a single JSON Schema document, then all collection schemas will be defined in that document.
If target parameter collectionSchemaFileName has a non-empty value, all collection schema definitions are added to a new JSON Schema document with the name given by the parameter. The file will be located in the same directory as determined for the main schema package. The $id of the new JSON Schema document is created using the $id for the main schema package as a basis. If that id ends with ".json", only the substring until the last "/" is used as basis. The value of target parameter collectionSchemaFileName is appended (using "/" as join character, unless the basis already ends with that character).

Two aspects play an important role when creating the collection schema: a base collection schema as well as how the actual member checks are defined.

The base collection schema is determined as follows:

The conversion is based upon the assumption that the members of a collection are encoded in a JSON array.
The target parameter baseJsonSchemaDefinitionForCollections, if set, gives a reference to the base collection schema (which will be included in a particular collection schema using the "allOf" member). An example value would be https://geojson.org/schema/FeatureCollection.json - to reference the GeoJSON feature collection schema.
- If the parameter is not set, or has no value, it is assumed that collections are encoded as simple JSON arrays, without any further structure (which can be useful in a plain JSON encoding).
- If the parameter is set, then it is assumed that the JSON member that contains the array of collection members is the top-level "features" member. This is compatible with the GeoJSON feature collection. In the future, the path to that JSON member can be made configurable.

The member check is realized as follows:

Within the general "FeatureCollection", the check is realized using an "allOf", which bundles a number of if-then-constraints:
- One if-then-constraint per non-abstract feature type. The if-part checks the value of the entity type member against the name of the feature type. The then-part references the JSON Schema definition of the feature type.
- By default, the FeatureCollection allows objects of unknown type. Such objects are not validated, since none of the previously described if-constraints will match them. In order to forbid unknown members in a collection, set target parameter preventUnknownTypesInFeatureCollection to "true". In that case, another if-then-constraint is added:
  - if-part:
    
    If the paths to the entity type members of all the feature types are equal: not-constraint with the path to the entity type member and enum with the names of the feature types.
    
    Otherwise, i.e. the entity type member paths are not all equal: not-constraint with oneOf, with one schema per entity type member path, and an enum with the names of the feature types whose entity type member is at that path.
  - then-part: simply false.
For uniform collections, it depends on the represented feature type:
- In case the feature type is a supertype:
  - The member check is created using an "allOf" with a number of if-then-constraints, one per non-abstract class (in the set consisting of the feature types as well as its direct and indirect subtypes) - much like it is done for the general "FeatureCollection".
  - An additional if-then-constraint is used to validate objects of unknown type. However, other than for the general "FeatureCollection", here we have an actual schema to work with: that of the collection’s feature type.
- Otherwise, the feature type is a leaf class. In that case, the collection member check simply consists of a reference to the JSON Schema definition of the feature type.

2.2.8. rule-json-cls-collectionsWithTopLevelEntityType

(since v2.14.0)

Extends rule-json-cls-collectionsBasedOnEntityType to support cases in which the entity type member is not set per object, but on the collection level for all objects. This rule should only be applied if the assumption then is that all objects in the collection are of the same type.

Note	In order for rule-json-cls-collectionsWithTopLevelEntityType to work as expected, rule-json-cls-collectionsBasedOnEntityType should be part of the encoding rule as well.

This rule further assumes that baseJsonSchemaDefinitionForCollections is set, and that the base collection schema contains a top-level "featureType" member, which, if set, identifies the type of all collection members. In the following, that member is called collection-featuretype-member.

In order for the assumed mechanism to work in practice, it is necessary that both the collection-featuretype-member as well as the entity type members of collection member feature types are optional.

The implementation of the collection schemas created by rule-json-cls-collectionsBasedOnEntityType for the general "FeatureCollection" and the uniform collections for supertypes is extended. In the collection definition, the first "allOf" schema - which links the base schema defined by parameter baseJsonSchemaDefinitionForCollections with the member checks - is modified, so that the second schema consists of an if-then-else constraint:

The if-part checks via "required": ["featureType"] if the collection-featuretype-member is present in a given collection object. Note that the actual value is not checked here, including if the value is null. The mere presence of the collection-featuretype-member is assumed to indicate that it conveys the feature type name of all collection members.
The then-part contains an "allOf" with a number of if-then-constraints:
- For each relevant non-abstract feature type, an if-then-constraint is created, which checks the value of the collection-featuretype-member against the name of the feature type. The then-part contains a reference to the JSON Schema definition created for that feature type.
- Similar to rule-json-cls-collectionsBasedOnEntityType, a final if-then-constraint is created (though for the general "FeatureCollection", only if target parameter preventUnknownTypesInFeatureCollection is set to "true"). The constraint checks in the if-part that the collection-featuretype-member value is not equal to a name of one of the feature types. In the case of the general "FeatureCollection" (with target parameter preventUnknownTypesInFeatureCollection not being "true"), the then-part is then simply false. In case of a uniform collection for a supertype, the then-part is a reference to the schema of the collection feature type.
The else part of the if-then-else constraint contains the member check as created by rule-json-cls-collectionsBasedOnEntityType (assuming that the entity type member is present for each collection member).

Note	The encoding of uniform collections for leaf classes in rule-json-cls-collectionsBasedOnEntityType does not need to be extended, since it is completely independent of any entity type member checks.

2.2.9. rule-json-cls-defaultGeometry-multipleGeometryProperties

This conversion rule is typically used in case that a) a GeoJSON compliant encoding shall be created, and b) for application schemas with classes that have multiple geometry properties.

With this rule, a geometry property is identified as default geometry by setting tagged value defaultGeometry on the property to the value true. That property will then be encoded as a top-level "geometry" member. If multiple such properties exist (potentially inherited), none of them is selected as default geometry (because no informed choice can be made) and an error will be logged.

Note

(since v2.14.0) If the default geometry property is optional or voidable, then the schema restriction for the "geometry" member will define a choice - using the "oneOf" JSON Schema keyword - between a null value and the geometry schema definition for the value type of the geometry property (e.g., a GeoJSON Polygon in case of the property value type being GM_Surface).

Note	(since v2.14.0) If the geometry type of the default geometry property is NOT one of those defined by target parameter geoJsonCompatibleGeometryTypes, then the constraint for the "geometry" member will NOT be created.

2.2.10. rule-json-cls-defaultGeometry-singleGeometryProperty

This conversion rule is typically used in case that a) a GeoJSON compliant encoding shall be created, and b) for application schemas with classes that have at most one geometry property.

With this rule, the geometry property of a class represents the default geometry, and is encoded as the top-level "geometry" member. If a class has multiple - potentially inherited - geometry properties with different names, none of them is selected as default geometry (because no informed choice can be made) and ShapeChange will log an error.

Note

Note	(since v2.14.0) If the geometry type of the default geometry property is NOT one of those defined by target parameter geoJsonCompatibleGeometryTypes, then the constraint for the "geometry" member will NOT be created.

2.2.11. rule-json-cls-documentation-enumDescription

(since v2.14.0)

This rule extends rule-json-all-documentation by creating a new "enumDescription" annotation within the JSON Schema definition of an enumeration, with one member per encoded enum. The name of such a member is the initial value of the enum, if available, otherwise the enum name. The member value is a JSON object with annotation members created by applying the configured JSON Schema annotations to the enum. Note that if none of the annotation definitions creates an annotation value for the enum, then the JSON object will be empty.

2.2.12. rule-json-cls-genericValueType

(since v2.14.0)

Some domains use constructs like the one shown in Figure 1 to add extension points to their feature types. The generic attributes shown in this example contain a name and a (simple) value. They provide a specific place for additional key-value-pair based information.

Figure 1. Example schema with generic value types

There is a specific solution for supporting such structures in JSON.

The according conversion is enabled using rule-json-cls-genericValueType. The conversion rule is applied for a <<dataType>> whose name is contained in the (comma-separated) value of target parameter genericValueTypes. The subtypes will automatically be taken into account as well. For example: genericValueTypes=GenerAttribute

The JSON Schema definition for GenerAttribute, in plain JSON encoding, would be as follows:


  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

  {
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "$defs": {
    "GenerAttribute": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "value": {
          "type": ["string", "integer", "number"]
        }
      },
      "required": [
        "name",
        "value"
      ]
    }
  }
}

Only the plain type information from the value types of the common value property of the subtypes contributes to the type definition of the according JSON property. Any JSON Schema format keywords, defined for such value types, are ignored.

Note

rule-json-cls-genericValueType only looks for a single attribute that is common to all subtypes of the classes identified by target parameter genericValueTypes. Additional properties of these subtypes are ignored! Also, if multiple common properties exist, all will be ignored (and an error logged)!

The resulting JSON definition of GenerAttribute supports encoding of values for any of the actual subtypes of GenerAttribute.

Note	The JSON Schema definition allows for type checks and is more expressive than the definition that would be created by default for just GenerAttribute (with only the "name" attribute defined).

2.2.13. rule-json-cls-identifierForTypeWithIdentity

With rule-json-cls-identifierForTypeWithIdentity, an identifier JSON member will be added to the JSON object that represents a type with identity (feature type or object type). The key and value type of that member can be configured using ShapeChange JSON Schema target parameters:

objectIdentifierName: "id" (the default) or any other suitable string that does not conflict with other member names);
objectIdentifierType: "string" (the default), "number", or "string, number";
objectIdentifierRequired: "false" (the default) or "true" is used to define if the property is optional or required.

2.2.14. rule-json-cls-identifierStereotype

This conversion rule assumes that all types with identity (feature type or object type) have an attribute with stereotype «identifier» (directly, or inherited from a supertype). That attribute is used to encode the identifier. The rule is typically used in conjunction with rule-json-cls-ignoreIdentifier, in order to detect identifier properties and not encode them (e.g. because a JSON Schema that applies to all types with identity already defines an identifier member).

Note	If the maximum multiplicity of an «identifier» attribute is greater than 1, ShapeChange will log an error.

2.2.15. rule-json-cls-ignoreIdentifier

With this rule, the identifier of a type with identity (feature type or object type) will be encoded using an identifier member that is provided by a common base type (e.g. the "id" member of a GeoJSON Feature, to which a generalization relationship exists for a given feature type - see rule-json-cls-virtualGeneralization). That means that no additional identifier property is created. rule-json-cls-identifierForTypeWithIdentity is therefore overridden by rule-json-cls-ignoreIdentifier. Also, all identifier properties that are identified by rule-json-cls-identifierStereotype - if also included in the encoding rule - will simply be ignored when encoding the type with identity.

2.2.16. rule-json-cls-jsonFgGeometry

(since v2.14.0)

This rule takes into account the different options for encoding geometry values in JSON-FG features. The primary geometry property (identified via rule-json-cls-primaryGeometry, rule-json-cls-defaultGeometry-multipleGeometryProperties, or rule-json-cls-defaultGeometry-singleGeometryProperty) is encoded as JSON Schema constraints for the geometry and / or place members as follows:

If the geometry type of the primary geometry property is one of those defined by target parameter geoJsonCompatibleGeometryTypes: The JSON Schema constraint for the geometry type is created for both the "geometry" and the "place" member. A null value is allowed for both members.
Otherwise: The JSON Schema constraint for the geometry type is only created for the "place" member. A null value is only allowed for that member, if the primary geometry property is optional.
- NOTE: In this case, no specific constraints are created for the "geometry" member. When publishing data, for example in the GeoJSON compatibility mode, the publisher can thus choose a suitable way of deriving a value for the "geometry" member from the geometry that is encoded in the "place" member.

Warning

At the moment, this rule is only applicable for application schemas that do not define a secondary geometry! Issue 344 documents how the rule can be enhanced to support schemas with secondary geometry as well. That approach has not been implemented yet.

2.2.17. rule-json-cls-name-as-anchor

With rule-json-cls-name-as-anchor, the name of a class is encoded as an "$anchor", which is added at the start of the schema definition of the class (within the definitions schema). Schema definitions that have an "$anchor" can be referenced using the plain text value of the anchor as fragment identifier, instead of using a more complex JSON Pointer. However, pay attention to target parameter useAnchorsInLinksToGeneratedSchemaDefinitions and what is written in its documentation about the support of anchors in schema references.

Note	The "$anchor" keyword was added in JSON Schema draft 2019-09. It replaces the somewhat ambiguous use of the "$id" keyword in JSON Schema draft 07 to define plain name fragment identifiers for subschemas.

2.2.18. rule-json-cls-name-as-entityType

The rule adds another JSON member to the JSON object which represents the class (a feature or object type) that is being converted. The name of the JSON member can be configured using the target parameter entityTypeName. The JSON member is required and string-valued. It should be used to encode the name of the type that is represented by the JSON object.

Note

Since ShapeChange v2.14.0, this rule no longer applies to data types. The change was made for GeoJSON based applications where data type values are not converted to RDF/OWL using JSON-LD, and no entity type member checks are needed/encoded for JSON objects that represent data types. However, by adding rule-json-cls-name-as-entityType-dataType to the encoding rule, entity type members can still be created for data types.

An example for the benefit of encoding the type name in JSON objects is given in chapter 6 of the OGC Testbed-14: Application Schemas and JSON Technologies Engineering Report: Having a key within a JSON object with a string value that identifies the type of the object allows that object to be mapped to RDF. More specifically, the string value can be mapped to an IRI that identifies the type of an RDFS resource.

There are also some cases in which rule-json-cls-name-as-entityType is ignored or conditional:

To prevent the addition of unnecessary JSON members (here: because the JSON member would already be inherited), the rule is ignored for a type T if T is a subtype and rule-json-cls-name-as-entityType already applies to one of its supertypes.
By default, the rule does not apply to mixins, data types, unions, enumerations, and code lists.
However, if rule-json-cls-name-as-entityType-union is enabled together with rule-json-cls-name-as-entityType, then the latter also applies to unions. Likewise for data types (with rule-json-cls-name-as-entityType-dataType).
Since v2.14.0, encoding infos from external schemas - either from a base schema or from a supertype that is mapped to an external schema - can inform about the presence of an entity type member in the external schema. If such an external schema applies to a given type, then this conversion rule is ignored for that type.
- The base schema assignment is enabled via rule-json-cls-virtualGeneralization (and the target parameters identified there), and encoding infos for the base schema can be given via the target parameters baseJsonSchemaDefinitionForDataTypes_encodingInfos, baseJsonSchemaDefinitionForObjectTypes_encodingInfos, and baseJsonSchemaDefinitionForFeatureTypes_encodingInfos.
- Type mappings are documented here. The encoding infos of a mapped type are conveyed via map entry parameter encodingInfos.

2.2.19. rule-json-cls-name-as-entityType-dataType

(since v2.14.0)

If this rule is enabled together with rule-json-cls-name-as-entityType, then the latter also applies to data types.

2.2.20. rule-json-cls-name-as-entityType-union

If this rule is enabled together with rule-json-cls-name-as-entityType, then the latter also applies to unions.

Note

rule-json-cls-name-as-entityType-union has been implemented because with rule-json-cls-union-propertyCount unions are converted to JSON objects. The ontology target of ShapeChange encodes a union as a class, with cardinality restrictions to ensure that only one option (defined by the union) is used. For further details, also see the OGC Testbed-12 ShapeChange Engineering Report. This is an argument for applying rule-json-cls-name-as-entityType to unions, because it would support a JSON-LD based mapping to the union class in RDF/OWL.

2.2.21. rule-json-cls-nestedProperties

By default, the properties of a type with identity (feature type or object type) are converted to first-level properties of the resulting JSON object. In GeoJSON, feature properties are encoded within the GeoJSON "properties" member. Notable exceptions from that rule are the GeoJSON members "id", "geometry", and "bbox". In order to produce a JSON Schema that converts the properties of a type with identity to be encoded within a nested "properties" member - minus any properties that are mapped to the other aforementioned GeoJSON keys - the conversion rule rule-json-cls-nestedProperties needs to be included in the encoding rule.

2.2.22. rule-json-cls-primaryGeometry

(since v2.14.0)

This rule can be used to identify which UML property of a «FeatureType» should be encoded as a schema constraint for the top-level "geometry" member, and to create such a constraint. The rule can be applied when creating a GeoJSON-compliant encoding.

If a UML property has tag jsonPrimaryGeometry with value equal to, ignoring case, "true", and the property is directly owned (i.e., not inherited) by a «FeatureType», then that property is encoded as the primary geometry of the feature type.

If the set of (direct and inherited, but ignoring redefined) UML properties of a «FeatureType» only contains a single UML property with a geometric type, and that property is directly owned by the feature type, and that property does not have tag jsonPrimaryGeometry with value equal to, ignoring case, "false", then that property is encoded as the primary geometry of the feature type.

Note	That a property has a geometric type, i.e., a geometry as value type, can be determined if the property value type is mapped, and the map entry contains parameter geometry.

In the JSON Schema definition of the «FeatureType», the primary geometry property is encoded as a type restriction for the top-level "geometry" member. The primary geometry property itself is then not encoded within the normal properties of the JSON object.

Note

If the primary geometry property is optional or voidable, then the schema restriction for the "geometry" member will define a choice - using the "oneOf" JSON Schema keyword - between a null value and the geometry schema definition for the value type of the geometry property (e.g., a GeoJSON Polygon in case of the property value type being GM_Surface).

Note	If the geometry type of the primary geometry property is NOT one of those defined by target parameter geoJsonCompatibleGeometryTypes, then the constraint for the "geometry" member will NOT be created.

In instance data, the value of the primary geometry property must be encoded within the (GeoJSON) top-level "geometry" member of the JSON object that represents the «FeatureType».

Note	This rule overrides rule-json-cls-defaultGeometry-multipleGeometryProperties and rule-json-cls-defaultGeometry-singleGeometryProperty for cases in which the encoded type is a feature type.

2.2.23. rule-json-cls-primaryPlace

(since v2.14.0)

This rule is useful to restrict the value of the JSON-FG "place" member. The conversion behavior is as follows:

A UML property that is owned by a «FeatureType» and that has tag jsonPrimaryPlace with value equal to, ignoring case, "true", is encoded as a type restriction for the top-level "place" member. The UML property is not encoded within the normal properties of the JSON object.

Note

If the UML property is optional or voidable, then the schema restriction for the "place" member will define a choice - using the "oneOf" JSON Schema keyword - between a null value and the geometry schema definition for the value type of the UML property (e.g., a JSON-FG Polygon in case of the property value type being GM_Surface).

Note	In instance data, the value of such a property must be encoded within the (JSON-FG) top-level "place" member of the JSON object that represents the «FeatureType».

2.2.24. rule-json-cls-primaryTime

(since v2.14.0)

This rule is useful to restrict the value of the JSON-FG feature "time" member. The conversion rule identifies the primary instant and interval properties of a «FeatureType». Depending upon the characteristics of the identified properties, a JSON Schema restriction is created for the top-level "time" member.

Primary instant determination:

A UML property that is owned by a «FeatureType» and that has tag jsonPrimaryInstant with value equal to, ignoring case, "true", shall not be encoded within the "properties" member. Instead, it shall be encoded as a restriction for the top-level "time" member. How the restriction is encoded also depends on the presence of a primary interval (as explained in the following). The details for the "time" restriction encoding are given further below.

Note	In instance data, the value of such a property must be encoded within the (JSON-FG) top-level time/date or time/timestamp member of the JSON object that represents the «FeatureType».

Primary interval determination:

A UML property that is owned by a «FeatureType» and that has tag jsonPrimaryInterval with value equal to, ignoring case, one of the allowed values "start", "end", or "interval", must not be encoded within the "properties" member. Instead, it is encoded as a restriction for the top-level "time" member. How the restriction is encoded also depends on the presence of a primary instant (as explained before). The details for the "time" restriction encoding are given further below.

Note

The value types of UML properties that represent or contribute to the primary interval should be compatible with that use. For example, properties marked as primary interval start or end can have value type "Date", "DateTime", or "TM_Instant", whereas a property marked as primary interval can have value type "TM_Period". However, the target does not check or enforce these value types (because of the possibility of suitable custom value types being used in an application schema).

Note	In instance data, the value of properties that represent or constitute to the primary interval must be encoded within the (JSON-FG) time/interval member of the JSON object that represents the «FeatureType».

Constraints of a «FeatureType» regarding primary instant and interval:

A «FeatureType» must satisfy the following conditions:

At most one of the direct properties has tag jsonPrimaryInstant = "true".
At most one of the direct properties has tag jsonPrimaryInterval = "interval".
At most one of the direct properties has tag jsonPrimaryInterval = "start".
At most one of the direct properties has tag jsonPrimaryInterval = "end".
The use of "interval" and "start"/"end" are mutually exclusive within the direct properties of the «FeatureType»: If one direct property has tag jsonPrimaryInterval = "interval", none of the direct properties must have tag jsonPrimaryInterval equal to "start" or "end". Likewise, if one direct property has tag jsonPrimaryInterval equal to "start" or "end", none of the direct properties must have tag jsonPrimaryInterval = "interval".

The target will log errors if these conditions are not fulfilled.

Restriction of the "time" member:

The restriction encoding depends upon the characteristics of the primary instant and interval properties, more specifically, whether they are optional or required.

If the primary interval is given via interval start and/or end properties, the optionality of the primary interval is determined as follows:

Primary Interval Start

Primary Interval End

Result (primary interval is optional or required)

undefined

optional

required

undefined

optional

required

optional

required

optional

required

The encoding - depending upon the optionality of primary instant and primary interval - is identified in the following table.

Primary Instant

Primary Interval

Encoding

undefined

optional

required

undefined

optional

required

no restriction is necessary

oneof: (null, required time/interval)

required time/interval

oneof: (null, required time/date, required time/timestamp)

oneof: (required time/date, required time/timestamp)

no restriction is necessary

required time/interval

oneof: (required time/date, required time/timestamp)

allof: (required time/interval, (oneof: required time/date, required time/timestamp))

2.2.25. rule-json-cls-restrictExternalEntityTypeMember

(since v2.14.0)

This rule can be used to restrict the entity type member that the JSON Schema definition of a class (feature, object, or data type) receives through an external JSON Schema definition, either through mapping of a direct supertype to such a schema definition, or by rule-json-cls-virtualGeneralization.

The only restriction right now is to make the entity type member a required property.

Note

The according constraint is only defined for the last segment of the entity type member path.

The restrictions are only defined in the JSON Schema definition of the class that directly "inherits" the external JSON Schema definition (thereby avoiding duplicate constraints in JSON Schema definitions of potentially existing subtypes of that class).

The restriction of the entity type member will not be encoded in case that the encoding infos for the external JSON Schema definition (given via map entry or the target parameters baseJsonSchemaDefinitionForFeatureTypes_encodingInfos, baseJsonSchemaDefinitionForObjectTypes_encodingInfos, or baseJsonSchemaDefinitionForDataTypes_encodingInfos) indicate that the restriction would be superfluous. The log will inform the user about such a situation.

The rule does not apply if the entity type member was generated by rule-json-cls-name-as-entityType.

2.2.26. rule-json-cls-restrictExternalIdentifierMember

(since v2.14.0)

This rule can be used to restrict the identifier member that the JSON Schema definition of a class (feature, object, or data type) receives through an external JSON Schema definition, either through mapping of a direct supertype to such a schema definition, or by rule-json-cls-virtualGeneralization. The restrictions are defined by parameter idMemberEncodingRestrictions.

Note

Restrictions for the identifier member (concerning its type, format, obligation), defined by target parameter idMemberEncodingRestrictions, will not be encoded in case that the encoding infos for the external JSON Schema definition (given via map entry or the target parameters baseJsonSchemaDefinitionForFeatureTypes_encodingInfos, baseJsonSchemaDefinitionForObjectTypes_encodingInfos, or baseJsonSchemaDefinitionForDataTypes_encodingInfos) indicate that such restrictions would be incompatible or superfluous. The log will inform the user about such a situation.

The rule does not apply if the identifier member was generated by rule-json-cls-identifierForTypeWithIdentity or rule-json-cls-identifierStereotype. But note that both of these rules are ignored if rule-json-cls-ignoreIdentifier applies, in case of which rule-json-cls-restrictExternalIdentifierMember indeed does apply.

2.2.27. rule-json-cls-union-propertyCount

With this rule, a «union» is converted to the JSON Schema definition of a JSON object. Each union option is represented as an optional member of the JSON object. The choice between the options defined by the union is encoded using "maxProperties" = "minProperties" = 1. That is, the number of members that are allowed for the JSON object is restricted to exactly one.

An "additionalProperties": false is used to prevent any undefined properties.

2.2.28. rule-json-cls-union-typeDiscriminator

With this rule, a «union» is converted to a JSON Schema definition that represents a choice between the value types of the union properties.

If the value types are only simple, without a specific format definition, then the JSON Schema will only contain a "type" member, with an array of the simple types.
Otherwise, a "oneOf" member is added to the JSON Schema definition, with:
- one "$ref" per non-simple type,
- one "type" for all simple types without specific format, and
- one "type" per simple type with specific format.

2.2.29. rule-json-cls-valueTypeOptions

This rule looks for tagged value valueTypeOptions on a class (that is not a basic type, enumeration, or code list). If the tag exists and has a value, it defines which types are allowed as value type for a given UML property of the class. Note that this UML property can be directly defined on the class but also be inherited from a supertype. The property can also originally have been an association role that belonged to an association class. The conversion rule ensures that instead of the actual value type of the property, only one of the allowed types is encoded as type definition in the JSON Schema. The conversion also takes into account that the property may have been a role of an association class. The restriction to a set of allowed types uses an if-then-else construct, which depends on the presence of a type identifying member in property values, and thus rule-json-cls-valueTypeOptions should always be used in combination with rule-json-cls-name-as-entityType. Note that value type restrictions (defined on a subtype) of inherited UML properties will result in these properties being explicitly defined in the JSON Schema definition of the subtype.

Note	Value type options can be parsed from OCL constraints using transformation rule-trf-cls-constraints-valueTypeRestrictionToTV-exclusion of the Constraint Converter.

2.2.30. rule-json-cls-virtualGeneralization

It is often useful to encode all classes with a certain stereotype with a common base type. The generalization relationship to such a base type is often implied with the stereotype, for a given encoding. In GML, for example, the common base type for classes with stereotype «featureType» is gml:AbstractFeature. Rather than explicitly modeling such a base type (e.g. AnyFeature defined by ISO 19109), as well as explicitly modeling generalization relationships to the base type, the encoding rule typically takes care of adding that relationship to relevant schema types.

This kind of virtual generalization is supported via rule-json-cls-virtualGeneralization. The rule adds generalization relationships to specific kinds of classes - if a) according ShapeChange JSON Schema target parameters have been set, and b) the class does not already have that generalization relationship via one of its supertypes:

feature type - configuration parameter baseJsonSchemaDefinitionForFeatureTypes
object type - configuration parameter baseJsonSchemaDefinitionForObjectTypes
data type - configuration parameter baseJsonSchemaDefinitionForDataTypes

The parameter value shall be a URI to reference the JSON Schema that defines the common base type. For example, in order for all feature types to use the GeoJSON Feature definition as common base, set baseJsonSchemaDefinitionForFeatureTypes = https://geojson.org/schema/Feature.json.

Note	The parameters do not have a default value. If a parameter is not set or does not have a value, then rule-json-cls-virtualGeneralization will not have an effect for the kind of class (feature, object, or data type) for which the parameter applies.

The virtual generalization relationship is implemented by converting the class to a JSON Schema that consists of an "allOf" with two subschemas: the first being a "$ref" with the URI defined by the target parameter, the second being the schema produced by applying the other conversion rules to the class (the only exception being rule-json-cls-name-as-anchor, because the "$anchor" created by that rule is not encoded in the second subschema, but in the schema that contains the "allOf").

2.2.31. rule-json-prop-derivedAsReadOnly

With this rule, a UML property marked as derived will be encoded with "readOnly": true.

2.2.32. rule-json-prop-initialValueAsDefault

With this rule, the JSON Schema definition of a UML attribute that has an initial value, is not owned by an enumeration or code list, and whose value type is mapped to "string", "number", or "boolean", will include the "default" annotation with that value.

Note

The value of the annotation can have any JSON value type. The initial value is encoded accordingly: quoted, if the property type is "string", unquoted if the property type is "number", and true if the property type is "boolean" and the initial value is equal to, ignoring case, "true"; otherwise the value will be false. Theoretically, the default value can also be a JSON array or object, but that cannot be represented in UML and thus is not a relevant use case.

2.2.33. rule-json-prop-inlineOrByReferenceTag

(since v2.14.0)

This rule overrides target parameter inlineOrByReferenceDefault, by defining the default value for tag inlineOrByReference of a UML property, for cases in which the tag is undefined or has an empty value, and the value type is a type with identity that is not implemented as a simple JSON Schema type. The default tag value then is:

inline, in case that the UML property is an attribute, and
byReference, in case that the UML property is an association role.

2.2.34. rule-json-prop-measure

(since v2.14.0)

With this rule, a property whose value type is one of the ISO 19103 measure types - as indicated via map entries with parameter measure - is encoded as follows:

If tagged value unit is defined on the UML property, with a non-blank value, then member "type" with value "number", and member "unit", with value being the value of tag unit, are encoded in the JSON Schema definition of the property.
Otherwise, i.e., tag unit is undefined on the property, member "$ref" is added to the definition, with value being defined by target parameter measureObjectUri. The referenced schema defines the structure of a measure object.

2.2.35. rule-json-prop-readOnly

With this rule, the JSON Schema definition of a UML property that is read only or fixed will include the "readOnly" annotation with JSON value true.

2.2.36. rule-json-prop-voidable

With this rule, the JSON Schema of a UML property with stereotype «voidable», or with tagged value nillable = true, is defined in a way that only allows either a null value or a(n array of) actual value(s).

If the UML property has maximum multiplicity 1, then a simple "type" restriction with value "null" is added to the type definition that is produced for the property.
Otherwise - the maximum multiplicity is greater than 1 - a choice (encoded using the "oneOf" keyword) between a "null" value and an array of actual values will be created.

2.3. Rule execution priority and dependencies

Some of the conversion rules supported by this target address the same conversion aspects. When conflicting conversion rules are included in the encoding rule, ShapeChange usually only executes one of them. This section documents the execution priorities and dependencies of rules that address the same conversion aspects.

2.3.1. Code lists

The default behavior for encoding code lists is overridden whenever either rule-json-cls-codelist-link or rule-json-cls-codelist-uri-format is in the encoding rule.

These conversion rules are executed with the following priority:

2.3.2. Identifier

With rule-json-cls-identifierForTypeWithIdentity, an identifier member can be added to the JSON Schema representation of a type with identity (feature type or object type). That rule will be ignored if rule-json-cls-ignoreIdentifier also applies to the type with identity.

2.3.3. Union

The rules for converting unions are executed with the following priority:

2.3.4. Geometry

When determining if a UML property of a «FeatureType» should be encoded as a restriction of the top-level "geometry" member, and otherwise be ignored (i.e., not encoded in the normal properties of the JSON object), rule-json-cls-primaryGeometry overrides (i.e., has a higher priority than) rule-json-cls-defaultGeometry-multipleGeometryProperties and rule-json-cls-defaultGeometry-singleGeometryProperty.

2.4. Parameters

This target supports the parameters defined in the following subsections.

2.4.1. baseJsonSchemaDefinitionForCollections

(since v2.14.0)

Required / Optional: optional

Type: URI

Default Value: none

Explanation: Reference to the JSON Schema definition which shall be used as base schema for collection definitions generated by rule-json-cls-collectionsBasedOnEntityType.

Applies to Rule(s): rule-json-cls-collectionsBasedOnEntityType

2.4.2. baseJsonSchemaDefinitionForDataTypes

Required / Optional: optional

Type: URI

Default Value: none

Explanation: Reference to the JSON Schema definition which shall be added to a data type in order to represent an additional generalization relationship under rule-json-cls-virtualGeneralization.

Applies to Rule(s): rule-json-cls-virtualGeneralization

2.4.3. baseJsonSchemaDefinitionForDataTypes_encodingInfos

(since v2.14.0)

Required / Optional: optional

Type: String

Default Value: none

Explanation: Provides additional information about the JSON structure that is represented by the JSON Schema definition given by parameter baseJsonSchemaDefinitionForDataTypes. The additional information can be relevant for creating a JSON encoding for data types (e.g., restricting an entity type member).

The value of this parameter follows the structure of the the map entry parameter encodingInfos. The semicolon is used as separator. However, no curly braces are used. Example:

<TargetParameter name="baseJsonSchemaDefinitionForDataTypes_encodingInfos" value="entityTypeMemberPath=type;entityTypeMemberRequired=false"/>

Applies to Rule(s):

2.4.4. baseJsonSchemaDefinitionForFeatureTypes

Required / Optional: optional

Type: URI

Default Value: none

Explanation: Reference to the JSON Schema definition which shall be added to a feature type in order to represent an additional generalization relationship under rule-json-cls-virtualGeneralization.

Applies to Rule(s): rule-json-cls-virtualGeneralization

2.4.5. baseJsonSchemaDefinitionForFeatureTypes_encodingInfos

(since v2.14.0)

Required / Optional: optional

Type: String

Default Value: none

Explanation: Provides additional information about the JSON structure that is represented by the JSON Schema definition given by parameter baseJsonSchemaDefinitionForFeatureTypes. The additional information can be relevant for creating a JSON encoding for feature types (e.g., restricting an entity type member).

The value of this parameter follows the structure of the the map entry parameter encodingInfos. The semicolon is used as separator. However, no curly braces are used. Example:

<TargetParameter name="baseJsonSchemaDefinitionForFeatureTypes_encodingInfos" value="entityTypeMemberPath=featureType;entityTypeMemberRequired=false;idMemberPath=id;idMemberTypes=string,number;idMemberRequired=false"/>

Applies to Rule(s):

2.4.6. baseJsonSchemaDefinitionForObjectTypes

Required / Optional: optional

Type: URI

Default Value: none

Explanation: Reference to the JSON Schema definition which shall be added to an object type in order to represent an additional generalization relationship under rule-json-cls-virtualGeneralization.

Applies to Rule(s): rule-json-cls-virtualGeneralization

2.4.7. baseJsonSchemaDefinitionForObjectTypes_encodingInfos

(since v2.14.0)

Required / Optional: optional

Type: String

Default Value: none

Explanation: Provides additional information about the JSON structure that is represented by the JSON Schema definition given by parameter baseJsonSchemaDefinitionForObjectTypes. The additional information can be relevant for creating a JSON encoding for object types (e.g., restricting an entity type member).

The value of this parameter follows the structure of the the map entry parameter encodingInfos. The semicolon is used as separator. However, no curly braces are used. Example:

<TargetParameter name="baseJsonSchemaDefinitionForObjectTypes_encodingInfos" value="entityTypeMemberPath=type;entityTypeMemberRequired=false;idMemberPath=id;idMemberTypes=string;idMemberRequired=false"/>

Applies to Rule(s):

2.4.8. byReferenceFormat

(since v2.14.0)

Required / Optional: optional

Type: Enum (one of "uri" and "uri-reference")

Default Value: "uri"

Explanation: Defines the format for the "by reference" encoding of a UML property, in case that target parameter byReferenceJsonSchemaDefinition is not set.

Applies to Rule(s): The parameter applies both for the default behavior of encoding "by reference", as well as for rule-json-all-featureRefs.

2.4.9. byReferenceJsonSchemaDefinition

Required / Optional: optional

Type: URI

Default Value: none

Explanation: References a JSON Schema definition which shall be used to encode the value of a UML property "by reference", i.e. somehow link to the actual value. That is relevant for cases in which tag inlineOrByReference of the UML property (taking into account target parameter inlineOrByReferenceDefault) has value byReference or inlineOrByReference. By setting this parameter, the default encoding for the "by reference" case - which is "type": "string", and "format" with value defined by parameter byReferenceFormat - can be overridden.

Applies to Rule(s): none - default behavior

2.4.10. collectionSchemaFileName

(since v2.14.0)

Required / Optional: optional

Type: String

Default Value: none

Explanation: The name of the file to which all collection definitions shall be added, for example "collections.json". If the file name does not end with ".json", that suffix is added to the file name.

Note

If target parameter featureCollectionOnly is set to "true", then only the general feature collection is generated. In that case, also a "$ref" to the definition of the general feature collection is added to the collection schema (when encoded in a separate file using target parameter collectionSchemaFileName).

Applies to Rule(s): rule-json-cls-collectionsBasedOnEntityType

2.4.11. defaultEncodingRule

Required / Optional: optional

Type: String

Default Value: *

Explanation: The identifier of the default encoding rule governing the conversion to JSON Schema. To use a custom encoding rule defined in the configuration, simply provide the name of the custom encoding rule via this parameter.

Applies to Rule(s): none - default behavior

2.4.12. entityTypeName

Required / Optional: optional

Type: String

Default Value: "entityType"

Explanation: The name of the JSON member to be added to a JSON object in order to encode the type represented by that object.

Applies to Rule(s): rule-json-cls-name-as-entityType

2.4.13. featureCollectionOnly

(since v2.14.0)

Required / Optional: optional

Type: Boolean

Default Value: false

Explanation: If this parameter is set to "true", then only the general feature collection is created. The uniform collections (one per feature type) are not created.

Applies to Rule(s): rule-json-cls-collectionsBasedOnEntityType

2.4.14. featureRefIdTypes

(since v2.14.0)

Required / Optional: optional

Type: String - one of "string", "integer", or a (comma-separated) combination thereof.

Default Value: "integer"

Explanation: The type of feature identifiers in non-external collection(s).

Note	In future, more sophisticated ways of determining the feature identifier type can be designed and implemented.

Applies to Rule(s): rule-json-all-featureRefs

2.4.15. featureRefProfiles

(since v2.14.0)

Required / Optional: optional

Type: String - one of "rel-as-link", "rel-as-uri", "rel-as-key", or a (comma-separated) combination thereof.

Default Value: "rel-as-link"

Explanation: Defines the profiles to support for encoding feature references. If multiple profiles are chosen, a choice using the "oneOf" JSON Schema keyword is created.

Warning

Pay attention that when "rel-as-uri" and "rel-as-key" are combined, then there is a danger of overlapping type definitions, in case that key-based references only consist of the feature id and the type of that id also is a string. In that case, JSON data may not be valid against the resulting JSON Schema, since the oneOf would not be satisfied for each case of a string-encoded feature id.

Applies to Rule(s): rule-json-all-featureRefs

2.4.16. featureRefWithAnyCollectionId

(since v2.14.0)

Required / Optional: optional

Type: Boolean

Default Value: false

Explanation: True if non-external feature references shall not restrict the value of the "collectionId" member, else false.

Applies to Rule(s): rule-json-all-featureRefs

2.4.17. genericValueTypes

(since v2.14.0)

Required / Optional: optional

Type: (comma-separated list of) string(s)

Default Value: none

Explanation: Identifies the classes that represent the roots of generic value type inheritance trees, which shall be encoded as defined by rule-json-cls-genericValueType.

Applies to Rule(s): rule-json-cls-genericValueType

2.4.18. geoJsonCompatibleGeometryTypes

(since v2.14.0)

Required / Optional: optional

Type: (comma-separated list of) String(s)

Default Value: GM_Point, GM_Curve, GM_Surface, GM_MultiPoint, GM_MultiCurve, GM_MultiSurface

Explanation: Set of types (typically from ISO 19107), that are defined as being compatible with GeoJSON geometry types. Geometric properties that have one of these types can be encoded as JSON Schema constraints for the geometry-member.

Applies to Rule(s):

2.4.19. idMemberEncodingRestrictions

(since v2.14.0)

Required / Optional: optional

Type:

Default Value: none

Explanation: Can be used to restrict the identifier member that is incorporated from an external JSON Schema definition. The value is a semicolon-separated list of restrictions:

typeRestriction: For restricting the type of the ID member. The value is either "string", "number", or "integer".
formatRestriction: For restricting the format of the ID member. The value is a comma-separated list of values for JSON Schema keyword "format".
memberRequired: The presence of this key (i.e., without a specific value) defines that the ID member shall be declared as a required property. Note that the according constraint is only defined for the last segment of the ID member path.

Example: <TargetParameter name="idMemberEncodingRestrictions" value="typeRestriction=string;formatRestriction=uuid;memberRequired"/>

Applies to Rule(s): rule-json-cls-restrictExternalIdentifierMember

2.4.20. inlineOrByReferenceDefault

Required / Optional: optional

Type: Enumeration, one of "inline", "byReference", "inlineOrByReference"

Default Value: "byReference"

Explanation: Defines the default value for tag inlineOrByReference of a UML property, in case that tag is undefined or has an empty value for the property.

Note	(since v2.14.0) This parameter is ignored for a given UML property, if rule-json-prop-inlineOrByReferenceTag is in the encoding rule that applies to that property.

Applies to Rule(s): none - default behavior

2.4.21. jsonBaseUri

Required / Optional: optional

Type: URI

Default Value: http://example.org/FIXME

Explanation: The base URI, used to construct the value of the "$id" members of resulting JSON Schemas.

Note	If the tagged value jsonBaseUri of an application schema has a non empty value, then that value will be used as base URI for all JSON Schemas produced for the content of that application schema.

Important

(since v2.14.0) If the application schema has tagged value jsonId with a non empty value, then that value will be used as value of the "$id" member, overruling the default mechanism of constructing that value using the template {jsonBaseUri}/{jsonDirectory}/{jsonDocument}.

Also:

The file name given in tag jsonDocument should match the file name in the jsonId (if the path of the URI given there contains a file name). However, it is not required to do this, if the file is re-named during the publication process.
If tag jsonDocument is set on sub-packages of the application schema, then tag jsonId should also be set for those packages. Otherwise, the fallback of schema-ID creation using the template (see above) would be applied.

Applies to Rule(s): none - default behavior

2.4.22. jsonSchemaVersion

Required / Optional: optional

Type: Enumeration, one of "2020-12", "2019-09", "draft-07", "OpenApi30"

Default Value: "2019-09"

Explanation: Specifies the version of the resulting JSON Schemas.

Applies to Rule(s): none - default behavior

2.4.23. linkObjectUri

Required / Optional: optional

Type: URL

Default Value: none

Explanation: Reference to the JSON Schema of the "Link" object.

Applies to Rule(s): rule-json-cls-codelist-link

2.4.24. measureObjectUri

(since v2.14.0)

Required / Optional: optional

Type: URL

Default Value: FIXME

Explanation: Reference to the JSON Schema of the "Measure" object.

Applies to Rule(s): rule-json-prop-measure

2.4.25. objectIdentifierName

Required / Optional: optional

Type: String

Default Value: "id"

Explanation: Name of the JSON member to be added to a JSON object that represents the type with identity.

Applies to Rule(s): rule-json-cls-identifierForTypeWithIdentity

2.4.26. objectIdentifierRequired

Required / Optional: optional

Type: Boolean

Default Value: false

Explanation: "false", if the new object identifier member shall not be required, else "true"

Applies to Rule(s): rule-json-cls-identifierForTypeWithIdentity

2.4.27. objectIdentifierType

Required / Optional: optional

Type: String - one of "string", "number", or a (comma-separated) combination thereof

Default Value: "string"

Explanation: Value type of the JSON member to be added to a JSON object that represents the type with identity.

Applies to Rule(s): rule-json-cls-identifierForTypeWithIdentity

2.4.28. outputDirectory

Required / Optional: optional

Type: String

Default Value: <the current run directory>

Explanation: The path to which the JSON Schema file(s) will be written.

Applies to Rule(s): none - this is a common target parameter

2.4.29. prettyPrint

Type: Boolean

Default Value: true

Explanation: True if the resulting json schemas shall be pretty printed, else false.

Applies to Rule(s): none – default behavior

2.4.30. preventUnknownTypesInFeatureCollection

(since v2.14.0)

Required / Optional: optional

Type: Boolean

Default Value: false

Explanation: "false", if objects of unknown type shall be allowed (and ignored) in the general "FeatureCollection"; "true", if such objects shall cause the validation to fail.

Applies to Rule(s): rule-json-cls-collectionsBasedOnEntityType

2.4.31. sortedOutput

Type: String

Default Value: "false"

Explanation:

If "false", the types in a schema will be processed in random order.
If "true", the types will be processed alphabetically.
If "taggedValue=<tag>", the types will be processed in the order of the values of the tagged value with name "<tag>".

Applies to Rule(s): none - this is a common target parameter

2.4.32. useAnchorsInLinksToGeneratedSchemaDefinitions

(since v2.14.0)

Required / Optional: optional

Type: Boolean

Default Value: true

Explanation: If set to "false", then the fragment identifier of a link to a schema definition that is generated by the target is always created as a JSON Pointer (e.g., #/$defs/XYZ). Setting this parameter to "true" means that the fragment identifier should use the anchor of the referenced schema definition (e.g., #xyz). However, that is only possible if the definition has an anchor (for further details, see rule-json-cls-name-as-anchor). If a given schema definition has no anchor, ShapeChange will automatically use a JSON Pointer when referencing that schema definition.

The reason why there is a configuration option to control whether JSON Pointers or anchors should be used in fragment identifiers of schema references is that anchors may not always be supported. In theory, anchors are only supported as fragment identifier if the schema is served with content type application/schema+json. A JSON Schema validator may not be able to handle a schema reference with anchor as fragment identifier, if the schema is not served with that content type (a reason could be that the validator then thinks that the fragment identifier has to be a JSON Pointer, and parses the fragment identifier as such).

So, even if the referenced schema definition has an anchor, it may still be served with a content type that does not support anchors, which requires schema references to be created using JSON Pointers. Target parameter useAnchorsInLinksToGeneratedSchemaDefinitions supports controlling the generation of fragment identifiers. If the generated schemas will be published with a content type other than application/schema+json, or if it is known that JSON Schema validators that need to work with the generated schemas only support JSON Pointers as fragment identifiers (for whatever reason), or if in doubt, then set parameter useAnchorsInLinksToGeneratedSchemaDefinitions to "false".

Note	If the schemas are generated for OpenAPI 3.0 (value of target parameter jsonSchemaVersion is "OpenApi30"), then anchors are not supported at all, and JSON Pointers will always be used as fragment identifier.

Note	For references to external schema definitions, the link given in the map entry defines the syntax to use.

Applies to Rule(s): none - this is a common target parameter

2.4.33. writeMapEntries

Required / Optional: optional

Type: Boolean

Default Value: false

Explanation: If set to "true", a map entry file will be written for each processed schema, containing a map entry for each encoded type from that schema.

Applies to Rule(s): none - this is a common target parameter

3. Map Entries

<mapEntries> contain individual <MapEntry> elements, which for this target contain information for mapping specific types (classes) from the UML model to either JSON Schema simple types, or using references to specific JSON Schema definitions.

Examples:


  1
2
3
4
5
6
7
8
9
10

  <mapEntries>
 <MapEntry type="CharacterString" rule="*" targetType="string" param=""/>
 <MapEntry type="URI" rule="*" targetType="string" param="keywords{format=uri}"/>
 <MapEntry type="Boolean" rule="*" targetType="boolean" param=""/>
 <MapEntry type="Integer" rule="*" targetType="integer" param=""/>
 <MapEntry type="Real" rule="*" targetType="number" param=""/>
 <MapEntry type="Measure" rule="*" targetType="number" param=""/>
 <MapEntry type="DateTime" rule="*" targetType="string" param="keywords{format=date-time}"/>
 <MapEntry type="GM_Point" rule="*" targetType="https://geojson.org/schema/Point.json" param="geometry"/>
</mapEntries>

A <MapEntry> element contains the attributes described in the following sections.

Note

StandardMapEntries_JSON.xml defines standard mappings for a number of types of the ISO Harmonized Model. This file can be included in ShapeChange configuration files (via XInclude - see the configuration example). Additional XInclude files, or individual <MapEntry> elements added to the <mapEntries> section of the configuration file, may be used to customize the map entries to support additional pre-defined conceptual UML classes.

3.1. type

Required / Optional: Required

Explanation: The unqualified UML type/class name to be mapped. Should be unique within the model (if it is not unique, this can lead to unexpected results).

3.2. rule

Required / Optional: Required

Explanation: The encoding rule to which this mapping applies. May be "*" to indicate that the mapping applies to all encoding rules.

3.3. targetType

Required / Optional: Required

Explanation: Name of a simple JSON Schema type (boolean, number, integer, or string), or a reference to a particular JSON Schema, typically expressed as a URL.

3.4. param

Required / Optional: Optional

Explanation: Defines one or more parameters for the mapping. If no parameter is provided (leaving the 'param' attribute empty) then the map entry contains a straightforward mapping.

Each parameter has a name. A list of parameters is separated by commas. Each parameter can also have characteristics defined for it, providing even further information for the conversion. Characteristics for a parameter are provided within curly braces. A characteristic usually is provided by a key-value pair, with the key being the identification of the characteristic.

Examples:

geometry
keywords{format=date}

Supported parameters, their interpretation as well as characteristics are described in the following sections.

3.4.1. Parameter: collectionInfos

Explanation: Provides additional information about the feature collection(s) in which data for the mapped type is stored.

Characteristics:

collectionIds: Identifiers of the collections in which data for the mapped type is stored. Can be a comma-separated list of identifiers, in case that the data may be spread across multiple collections (e.g. if the type has subtypes). Can also be omitted, which can be useful for cases in which the collection identifiers are not fully defined at schema creation time.
collectionIdTypes: The type of the feature identifiers used in the collection(s). "string", "integer", or a (comma-separated) list thereof. Optional; default is "integer".
uriTemplate: This characteristic is required for the map entry parameter collectionInfos. The value is a URI - typically a URL - template for links that reference the members of OGC API Features collection(s). The template must contain variable (featureId). It may also contain variable (collectionId). If the latter variable is not present, then the template must necessarily address only a single collection, and the characteristic collectionIds will be ignored by ShapeChange. Note that ShapeChange will convert the parentheses of the variables to curly brackets. The parentheses are only necessary because the encoding of a map entry parameter uses curly brackets for its characteristics, too.

3.4.2. Parameter: keywords

Explanation: Indicates that the simple JSON type (boolean, number, integer, string) that is the target of the map entry has one or more restrictions defined by JSON Schema keywords. The following keywords are supported - they also represent the characteristics of the parameter:

for any simple JSON type: keyword format
for JSON type string: keywords enum, const, pattern, maxLength, minLength
- NOTE: Complex regular expressions intended to be used as pattern may need to be base64 encoded, in order to avoid problems with syntax rules of the map entry parameter. For base64 encoded regular expressions, use the patternBase64 characteristic (instead of pattern).
for JSON types integer and number: keywords enum, const, multipleOf, maximum, minimum, exclusiveMaximum, exclusiveMinimum

Note	Multiple keywords may be specified as a semicolon-delimited list, e.g.: "keywords{minimum=0;maximum=3}".

3.4.3. Parameter: encodingInfos

Explanation: Provides additional information about the JSON encoding of the type, which is relevant for creating a JSON encoding that uses that type.

Characteristics:

entityTypeMemberPath: The path to the JSON member that is used to encode the type name. Only used if the JSON encoding actually has such a member. Examples:
- a plain JSON encoding: "@type"
- a nested JSON encoding, e.g. GeoJSON encoding: "properties/@type"
- JSON-FG encoding: "featureType"
entityTypeMemberRequired (supported since v2.14.0): true, if the property identified by characteristic entityTypeMemberPath is declared as required in the referenced JSON Schema definition, else false (the default). Example(s):
- JSON-FG encoding: "false"
idMemberPath (supported since v2.14.0): The path to the JSON member that is used to encode the ID. Only used if the JSON encoding actually has such a member. Examples:
- GeoJSON encoding: "id"
- JSON-FG encoding: "id"
idMemberRequired (supported since v2.14.0): true, if the property identified by characteristic idMemberPath is declared as required in the referenced JSON Schema definition, else false (the default). Examples:
- GeoJSON encoding: "false"
- JSON-FG encoding: "false"
idMemberTypes (supported since v2.14.0): (comma-separated) list of simple JSON Schema types, in which the value of the ID member (identified by idMemberPath) can be encoded. Allowed values are string, integer, number. The default value for this characteristic is string. Examples:
- GeoJSON encoding: "string,number"
- JSON-FG encoding: "string,number"
idMemberFormats (supported since v2.14.0): (comma-separated) list of format identifiers, which are assigned to keyword format for the ID member in the referenced JSON Schema definition. This characteristic has no default value.

3.4.4. Parameter: geometry

Explanation: Indicates that the map entry contains a mapping for a geometry type (specifically from ISO 19107). IMPORTANT: If geometry types are not identified via map entries containing this parameter then ShapeChange cannot determine geometry typed properties, which is relevant for default geometry encoding!

Characteristics: no specific characteristics are defined for this parameter

3.4.5. Parameter: ignoreForTypeFromSchemaSelectedForProcessing

Explanation: Set this parameter on map entries for types from external schemas, whose type name is the same as one of the types from the schemas selected for processing. For example, the SWE Common 2.0 schema defines a type called 'Boolean' - which is the same name as a type from ISO 19103 ('Boolean'). If the parameter is set on a map entry for 'Boolean', then the type from the schema selected for processing is still encoded and used - otherwise it would not be encoded and instead mapped as defined by the map entry.

Characteristics: no specific characteristics are defined for this parameter

3.4.6. Parameter: measure

(since v2.14.0)

Explanation: Indicates that the map entry contains a mapping for a measure type (specifically from ISO 19103).

Important

If measure types are not identified via map entries containing this parameter then ShapeChange cannot determine measure typed properties, which is relevant for rule-json-prop-measure.

Characteristics: no specific characteristics are defined for this parameter

4. JSON Schema Annotations

(since v2.14.0)

The target supports two types of configuration elements for defining JSON Schema annotations.

SimpleAnnotation - For annotations with a simple JSON value, or an array thereof.
TemplateAnnotation - For annotations with a JSON string as value, or an array thereof, defined via a template that can include multiple descriptors and tagged values.

Note	Annotations are only created for a model element if rule-json-all-documentation is part of the applicable encoding rule.

Note

The JSON Schema annotation "examples" is an example for an annotation that has a JSON array as value, with the type of array items being unrestricted. In other words, the array can contain mixed value types. The "examples" annotation can thus have an array of strings (e.g., ["abc","xyz"]), numbers (e.g., [4,2]), booleans (e.g., [true, true]), and a mix thereof (e.g., ["abc", 2, true]) as value.

Note

ShapeChange JSON Schema annotation elements are not designed to support the creation of annotations with complex JSON arrays or objects as value. Only simple values, or an array thereof, can be created. So far, no use cases have been identified that require a more complex annotation value. In the future, if such use cases were identified, ShapeChange could be extended to support them.

The following two tables document the structure of the two ShapeChange JSON Schema annotation elements. Listing 1, Listing 2, and Listing 3 provide configuration examples.

Table 2. SimpleAnnotation
Configuration Information Item	Datatype & Structure	Required / Optional	Default Value	Description
annotation	string	Required	not applicable	Name of the JSON Schema annotation keyword that shall be added to the JSON Schema element which represents the UML model element.
A number of attributes are used to select relevant model elements. They are the same as described here.
arrayValue	boolean	Optional	false	If true, then the annotation value will always be encoded as an array, even if only a single value is present. Otherwise, the default behavior is to only encode multiple values within a JSON array.
descriptorOr TaggedValue	string	Required	not applicable	Either a descriptor-ID, identifying one of the well-known descriptors, or a string identifying a tagged value. In order to identify a tagged value, add prefix "TV:" to the name of the tagged value. If a tagged value is known to contain a list of values, combined in a string using a specific separator, and these values shall be used as individual values, rather than using the whole string as value, use the prefix "TV(separator):," followed by the tag name. ShapeChange will then split the tagged value around matches of the given separator (which is treated as a literal).
noValueBehavior	enum: ignore or populateOnce	Optional	ignore	Determines the behavior in case that no value is available for the descriptor or tagged value. ignore: No annotation is created. populateOnce: A single annotation is created, with the noValueValue being used as value.
noValueValue	string	Optional	the empty string	If the descriptor or tagged value has no value, then this information item provides the value to use instead (e.g., 0, or true).
type	enum: string, integer, number, boolean	Optional	string	Defines how ShapeChange will encode the values of the descriptor / tagged value. type = string: each value will be quoted type = integer: each value will be parsed as an integer (invalid values will be ignored, and a warning logged); values will not be quoted type = number: each value will be parsed as a double (invalid values will be ignored, and a warning logged); values will not be quoted type = boolean: if the value is "true" (ignoring case") or 1, the value will be encoded as the JSON value true; otherwise, it will be encoded as the JSON value false.

Table 3. TemplateAnnotation
Information Item	Datatype & Structure	Required / Optional	Default Value	Description
annotation	as defined in the previous table
model element selection attributes, as defined in the previous table
arrayValue	as defined in the previous table
valueTemplate	string	Required	not applicable	Textual template where an occurrence of the field "[[descriptor-ID]]" is replaced with the value(s) of that descriptor. The IDs of supported descriptors are listed in Table 1. An occurrence of the field "[[TV:name]]" is replaced with the value(s) of the UML tagged value with the given name from the input schema. The content of a tagged value can also be split into multiple parts. In that case, use field "[[TV(separator):name]]." The tagged value will be split around matches of the given separator (which is treated as a literal).
noValueBehavior	enum: ignore or populateOnce	Optional	ignore	Determines the behavior in case that no value is available for any of the fields (tagged values and descriptors) contained in the template. ignore: No annotation is created. populateOnce: A single annotation is created, with the noValueValue being used for all fields.
noValueValue	string	Optional	the empty string	If a descriptor used in a template has no value, then this information item provides the value to use instead (e.g., "N/A" or "FIXME").
multiValueBehavior	enum: either connectInSingle AnnotationValue or createMultiple AnnotationValues (note that the two enums are only split in this table cell for presentation purposes)	Optional	connectInSingle AnnotationValue	Specifies how a case where one or more of the descriptors and tagged values contained in the template have multiple values, shall be encoded. connectInSingleAnnotationValue: Multiple values of a descriptor or tagged value contained in the template are combined in a single string value, using the multiValueConnectorToken to connect them. createMultipleAnnotationValues: Multiple values for one or more descriptor or tagged value result in an array of annotation values, with one value for each combination of multi-valued descriptors / tagged values (resulting in a permutation of the values of each descriptor / tagged value contained in the template).
multiValue ConnectorToken	string	Optional	a single space character	If a descriptor or tagged value used in the valueTemplate has multiple values, and the multiValueBehavior is set to connectInSingleAnnotationValue, then the values are concatenated to a single string value using this token as connector between two values.

Note	Conversion rules exist to populate the annotations "default" and "readOnly" (see rule-json-prop-initialValueAsDefault, rule-json-prop-derivedAsReadOnly, and rule-json-prop-readOnly).

The annotation elements are configured within the <advancedProcessConfigurations> element of the JSON Schema target, as shown in Listing 1.

Listing 1. Configuration example for JSON Schema annotation elements


  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

  <Target class="de.interactive_instruments.ShapeChange.Target.JSON.JsonSchemaTarget" mode="enabled" inputs="model">
  <advancedProcessConfigurations>
    <JsonSchemaAnnotations>
      <annotations>
        <SimpleAnnotation annotation="title" descriptorOrTaggedValue="alias" noValueBehavior="ignore"/>
        <TemplateAnnotation annotation="description" valueTemplate="Definition: [[definition]]  Description: [[description]]" noValueValue="[None Specified]" noValueBehavior="populateOnce"/>
        <SimpleAnnotation annotation="unit" descriptorOrTaggedValue="TV:unit" noValueBehavior="ignore"/>
        <SimpleAnnotation annotation="label" descriptorOrTaggedValue="TV(|):aliasList" arrayValue="false"/>
        <SimpleAnnotation annotation="label2" descriptorOrTaggedValue="TV(|):aliasList" arrayValue="true"/>
        <SimpleAnnotation annotation="deprecated" descriptorOrTaggedValue="TV:deprecated" type="boolean"/>
        <SimpleAnnotation annotation="code" descriptorOrTaggedValue="TV:codeNumber" noValueBehavior="populateOnce" noValueValue="0" type="integer" modelElementType="Class"/>
        <SimpleAnnotation annotation="code" descriptorOrTaggedValue="TV:codeNumber" noValueBehavior="populateOnce" noValueValue="0" type="integer" modelElementType="Property"/>
        <TemplateAnnotation annotation="isDefinedBy" valueTemplate="http://example.org/view?i=[[TV(,):item]]" multiValueBehavior="createMultipleAnnotationValues"/>
        <SimpleAnnotation annotation="examples" descriptorOrTaggedValue="example" arrayValue="true"/>
      </annotations>
    </JsonSchemaAnnotations>
  </advancedProcessConfigurations>
  <targetParameter name="outputDirectory" value="testResults/json/documentation/json_schemas/plainjson"/>
  <targetParameter name="sortedOutput" value="true"/>
  <targetParameter name="jsonBaseUri" value="https://example.org/baseuri_from_config"/>
  <targetParameter name="linkObjectUri" value="http://example.org/jsonschema/link.json"/>
  <targetParameter name="byReferenceJsonSchemaDefinition" value="https://example.org/jsonschema/byreference.json"/>
  <targetParameter name="defaultEncodingRule" value="myPlainJson"/>
  <rules>
    <EncodingRule name="myPlainJson" extends="defaultPlainJson">
      <rule name="rule-json-all-documentation"/>
    </EncodingRule>
  </rules>
  <xi:include href="src/main/resources/config/StandardMapEntries_JSON.xml"/>
</Target>

The <advancedProcessConfigurations> element can also reference another XML file that contains the annotation definitions via an include element. That can be useful, in case that multiple JSON Schema target configurations use the same set of annotations.

Listing 2. Example of advancedProcessConfigurations element with include statement


  1
2
3

  <advancedProcessConfigurations>
  <xi:include href="./config/myJsonSchemaAnnotations.xml"/>
</advancedProcessConfigurations>

Listing 3. Example of included XML file with JSON Schema annotation elements


  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

  <?xml version="1.0" encoding="UTF-8"?>
<JsonSchemaAnnotations xmlns="http://www.interactive-instruments.de/ShapeChange/Configuration/1.1">
  <annotations>
    <SimpleAnnotation annotation="title" descriptorOrTaggedValue="alias" noValueBehavior="ignore"/>
    <TemplateAnnotation annotation="description" valueTemplate="Definition: [[definition]]  Description: [[description]]" noValueValue="[None Specified]" noValueBehavior="populateOnce"/>
    <SimpleAnnotation annotation="unit" descriptorOrTaggedValue="TV:unit" noValueBehavior="ignore"/>
    <SimpleAnnotation annotation="label" descriptorOrTaggedValue="TV(|):aliasList" arrayValue="false"/>
    <SimpleAnnotation annotation="label2" descriptorOrTaggedValue="TV(|):aliasList" arrayValue="true"/>
    <SimpleAnnotation annotation="deprecated" descriptorOrTaggedValue="TV:deprecated" type="boolean"/>
    <SimpleAnnotation annotation="code" descriptorOrTaggedValue="TV:codeNumber" noValueBehavior="populateOnce" noValueValue="0" type="integer" modelElementType="Class"/>
    <SimpleAnnotation annotation="code" descriptorOrTaggedValue="TV:codeNumber" noValueBehavior="populateOnce" noValueValue="0" type="integer" modelElementType="Property"/>
    <TemplateAnnotation annotation="isDefinedBy" valueTemplate="http://example.org/view?i=[[TV(,):item]]" multiValueBehavior="createMultipleAnnotationValues" />
    <SimpleAnnotation annotation="examples" descriptorOrTaggedValue="example" arrayValue="true"/>
  </annotations>
</JsonSchemaAnnotations>

5. Configuration Example


  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

  <Target class="de.interactive_instruments.ShapeChange.Target.JSON.JsonSchemaTarget" mode="enabled">
 <targetParameter name="outputDirectory" value="results/json_schema/2019-09"/>
 <targetParameter name="sortedOutput" value="true"/>
 <targetParameter name="jsonBaseUri" value="https://example.org/baseuri"/>
 <targetParameter name="byReferenceJsonSchemaDefinition" value="https://example.org/jsonschema/byreference.json"/>
 <targetParameter name="entityTypeName" value="@type"/>
 <targetParameter name="defaultEncodingRule" value="myGeoJson"/>
 <rules>
  <EncodingRule name="myGeoJson" extends="defaultGeoJson">
   <rule name="rule-json-cls-basictype"/>
   <rule name="rule-json-cls-codelist-uri-format"/>
   <rule name="rule-json-cls-name-as-entityType"/>
   <rule name="rule-json-cls-union-propertyCount"/>
   <rule name="rule-json-cls-valueTypeOptions"/>
  </EncodingRule>
 </rules>
 <xi:include href="https://shapechange.net/resources/config/StandardMapEntries_JSON.xml"/>
</Target>