7.3.1.  Definitions schema

Schema packages have the stereotype «applicationSchema», «schema», or an alias (e.g., using a specific language, like in German: «anwendungsschema»). An «applicationSchema» package represents an application schema according to ISO 19109. The stereotype «schema» has been introduced for packages that should be treated like application schemas, but do not contain feature types.

1

{

2

  "$schema": "http://json-schema.org/draft/2020-12/schema",

3

  "$id": "http://example.org/some-definitions-schema.json",

4

  "$defs": {

5

    "Class1": {

6

      "type": "object",

7

      "properties": {

8

        "prop1": {"type": "string"}

9

      },

10

      "required": ["prop1"]

11

    },

12

    "Class2": {

13

      "type": "object",

14

      "properties": {

15

        "prop2": {"type": "number"}

16

      },

17

      "required": ["prop2"]

18

    }

19

  }

20

}

Figure 2 — JSON Schema example of a definitions schema

Figure 3 — References between JSON Schemas using $ref with JSON pointers as values

It is up to the encoder to use an absolute or relative URI for a reference to a schema definition within an external JSON Schema file. A reference to a schema definition within the same JSON Schema file should be encoded as a relative URL that consists of a fragment identifier, either using a JSON Pointer (e.g., #/$defs/XYZ) or an anchor (e.g., #XYZ).

A link to a particular definition within a definitions schema requires the use of a JSON Pointer or an anchor in the fragment identifier of the link URL. JSON Pointer, chapter 6, explicitly states that the media type in which a JSON value is provided needs to support this kind of fragment identifier, and that this is not the case for the media type application/json. If a JSON Schema was published with this media type, then it is possible that the application ignores a fragment identifier (because the media type does not support fragment identifiers). If a JSON Schema is published with media type application/schema+json, using anchors and JSON Pointers as fragment identifiers is supported.

The JSON Schema should be published with media type application/schema+json — which is defined by the JSON Schema specification. The media type application/schema+json supports JSON Pointers and plain names as fragment identifiers. For further details, see JSON Schema core, chapter 5.

7.3.2.  Documentation

Descriptive information of application schema elements (packages, classes, attributes and association roles) may be encoded via JSON Schema annotations.

The documentation of an application schema element may be encoded using the JSON Schema “description” annotation. Additional annotations, such as “title” and “examples”, may be used as well, where applicable.

7.3.3.  Types

^\d{4}-\d{2}-\d{2}$

^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d)?(Z|((\+|-)\d{2}:\d{2}))$

^\d{2}:\d{2}:\d{2}(\.\d)?(Z|((\+|-)\d{2}:\d{2}))$

^(([^:/?#]+):)?(\/\/([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?$

1

{

2

  "$schema": "http://json-schema.org/draft/2020-12/schema",

3

  "$defs": {

4

    "TypeA": {

5

      "$anchor": "TypeA",

6

      "...": "..."

7

    },

8

    "TypeB": {

9

      "$anchor": "TypeB",

10

      "...": "..."

11

    }

12

  }

13

}

7.3.3.4.  Inheritance

JSON Schema does not support the concept of inheritance itself. In practice, an inheritance relationship is important in two areas:

• when defining the structure of a subtype, which inherits the properties of its supertypes through the generalization relationships to those supertypes, and

• when using a supertype as UML property value; in that case, subtypes can be used as property value, too, and validation is typically expected to check a value based upon its actual type — especially if a subtype is used as value.

Generalization can be represented in JSON Schemas. Validation of property values that are subtypes of the defined property value type cannot fully be represented in JSON Schema.

Requirement 7
Identifier	/req/core/generalization
Included in	Requirements class 1: /req/core
Statement	The generalization relationship of a subtype to its supertype shall be encoded by combining the structural constraints of the subtype and its supertype using the “allOf” JSON Schema keyword in the JSON Schema definition of the subtype.

Multiple inheritance is supported by adding all supertypes as elements of “allOf.”

Figure 5 — Example of type inheritance

1	{
2	"$schema": "http://json-schema.org/draft/2020-12/schema",
3	"$defs": {
4	"TypeA": {
5	"properties": {
6	"propertyA": {
7	"type": "number"
8	}
9	},
10	"required": [
11	"propertyA"
12	]
13	},
14	"TypeB": {
15	"allOf": [
16	{
17	"$ref": "#/$defs/TypeA"
18	},
19	{
20	"type": "object",
21	"properties": {
22	"propertyB": {
23	"type": "string"
24	}
25	},
26	"required": [
27	"propertyB"
28	]
29	}
30	]
31	}
32	},
33	"$ref": "#/$defs/TypeB"
34	}

Figure 6 — JSON Schema example for realizing generalization using "allOf"

This JSON object is valid against the schema:

{
  "propertyA": 2,
  "propertyB": "x"
}

Figure 7

This JSON object is invalid (because “propertyA” is missing) against the schema:

{
  "propertyB": "x"
}

Figure 8

NOTE 1  This also works for an encoding where the properties of a class are nested within a key-value pair (like “properties” for a GeoJSON encoding).

NOTE 2  The case where a property from a supertype is redefined by a property from the subtype is supported. Redefinition in UML requires that the value type of the subtype property is “kind of” the type of the redefined property of the supertype. Therefore, the property value, when encoded in JSON, would satisfy the JSON Schema constraints defined by both the subtype property and the redefined supertype property.

This approach to converting a generalization relationship has the following restrictions.

• The JSON Schema keyword “additionalProperties” cannot be set to false in the definitions of both the super- and the subtype.

• The approach is only defined for generalization relationships of feature, object, and data types. For unions, enumerations, and code lists, generalization relationships are not defined by ISO 19103:2015.

• It only converts the generalization relationship from subtype to supertype. It does not support the other direction of an inheritance relationship, i.e., specialization. Given a JSON object that encodes a subtype, and the JSON Schema of the supertype, then by validating the JSON object against that JSON Schema, only the constraints of the supertype are checked, but not all the constraints that apply to the subtype. That is an issue when encoding a UML property whose value type is or could be a supertype (via a subtype that is added by an external, so far unknown schema). Conceptually, the actual value of that property can be a supertype object, but it could just as well be an object whose type is a subtype of that supertype. This issue can only be solved to a certain degree with JSON Schema, as explained in OGC 20-012, section Class Specialization and Property Ranges.

7.3.3.8.  Enumeration

Requirement 10
Identifier	/req/core/enumerations
Included in	Requirements class 1: /req/core
A	An «Enumeration» shall be converted to a JSON Schema definition with a type defined by evaluating tagged value literalEncodingType on the enumeration. The tagged value literalEncodingType identifies the conceptual type that applies to the enumeration values. If the tagged value is not set on the enumeration, or has an empty value, then the literal encoding type is defined to be CharacterString.
B	The JSON Schema definition shall use the “enum” keyword to restrict the value to one of the enums from the enumeration. The “enum” value shall be an array with one element per enum defined by the enumeration. For each enum, the array element shall be the initial value of the enum, if defined, otherwise it shall be the name of the enum.

The literal encoding type is one of the types from ISO 19103, which are implemented as a simple JSON Schema type — see Table 6.

Table 6 — Literal encoding type

Conceptual type from ISO 19103	simple JSON Schema type
CharacterString	string
Real, Number	number
Integer	integer

Figure 9 — «Enumeration» example

1	{
2	"$schema": "http://json-schema.org/draft/2020-12/schema",
3	"$defs": {
4	"Enumeration1": {
5	"type": "number",
6	"enum": [-5, 0, 5.5]
7	},
8	"Enumeration2": {
9	"type": "string",
10	"enum": ["A","B","C"]
11	}
12	}
13	}

Figure 10 — Example of enumerations encoded in JSON Schema

7.3.3.9.  Basic Type

If a direct or indirect supertype of an application schema class is represented in JSON Schema by one of the simple JSON Schema types string, number, integer, or boolean, then that class represents a so called basic type. 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.

Requirement 11
Identifier	/req/core/basic-types
Included in	Requirements class 1: /req/core
A	If the direct supertype of a basic type is implemented as one of the simple JSON Schema types, then the JSON Schema definition of the basic type shall have a “type” member with that simple JSON Schema type as value, and potentially additional JSON Schema keywords — especially “format” — which may be defined for the JSON Schema implementation of the supertype (for further details, see Clause 7.3.3.1). Otherwise, the JSON Schema definition of the basic type shall reference the JSON Schema definition of its supertype using the “$ref” member. NOTE  If an official JSON Schema was published for the types defined in ISO 19103:2015, then the definitions of that schema could be referenced, instead of creating a “type” member.
B	For each tag listed in Table 7, add the corresponding JSON Schema keyword (as defined in the table) to the JSON Schema definition of the basic type, with the tag value as value, if all of the following conditions are met: The tag is defined on the basic type and has a non-blank value. The simple JSON Schema type with which the basic type (or its direct or indirect supertype) is implemented is one of the simple JSON Schema types for which the JSON Schema keyword is applicable (as defined in Table 7).
C	If one or more JSON Schema keywords listed in Table 7 are added to the JSON Schema definition of the basic type, and that definition does not declare a “type” member — i.e., it references the JSON Schema definition of its supertype via “$ref” — then an “allOf” keyword shall be used to combine the referenced schema definition and the list of additional JSON Schema keywords.

Table 7 — Basic type restrictions

tagged value (to define a restriction)	JSON Schema keyword	applicable JSON Schema type(s)
jsonFormat	format	string, number, integer
maxLength	maxLength	string
minLength	minLength	string
jsonPattern	pattern	string
minInclusive	minimum	number, integer
minExclusive	exclusiveMinimum	number, integer
maxInclusive	maximum	number, integer
maxExclusive	exclusiveMaximum	number, integer
NOTE 1  The JSON Schema keyword “format” is defined in chapter 7 of JSON Schema Validation: A Vocabulary for Structural Validation of JSON. The formats defined there (e.g., “date-time”, “uri”, and “json-pointer”) apply to JSON values of type string. Custom formats could apply to JSON values of type number and integer. NOTE 2  JSON Schema Validation: A Vocabulary for Structural Validation of JSON defines the JSON Schema keyword “pattern”. According to that specification, the value of the keyword should be a regular expression according to the ECMA-262 regular expression dialect. JSON Schema: A Media Type for Describing JSON Documents defines a number of recommendations for writing regular expressions in JSON Schema. NOTE 3  If the “format” keyword is used to restrict the structure of a JSON string, so that it matches a certain regular expression, then it is useful to add the “pattern” keyword as well, explicitly defining that regular expression (given that the regular expression follows an ECMA-262 regular expression dialect). The reason is that the “format” is first and foremost an annotation, so can be ignored by JSON Schema validators, whereas the “pattern” keyword will be evaluated by a JSON Schema validator. JSON Schema validators may treat the “format” keyword like an assertion, but that is not guaranteed. In any case, the “format” keyword helps to convey more information about the specific type of a JSON value (e.g., “date” instead of just “string”), and thus should not be omitted if a certain, well-known (i.e., defined by a JSON Schema vocabulary) format is applicable to a JSON value.

Figure 11 provides a detailed example that illustrates a number of cases. The JSON Schema encoding is shown in Figure 12.

Figure 11 — Basic types example

1	{
2	"$schema": "http://json-schema.org/draft/2020-12/schema",
3	"$defs": {
4	"EmailAddress": {
5	"allOf": [
6	{
7	"$ref": "#/$defs/MyCharacterString"
8	},
9	{
10	"format": "email"
11	}
12	]
13	},
14	"MyCharacterString": {
15	"type": "string"
16	},
17	"MyNumber": {
18	"type": "number"
19	},
20	"Number0to360": {
21	"allOf": [
22	{
23	"$ref": "#/$defs/NumberNonNegative"
24	},
25	{
26	"maximum": 360.0
27	}
28	]
29	},
30	"NumberMinus180toPlus180": {
31	"allOf": [
32	{
33	"$ref": "#/$defs/MyNumber"
34	},
35	{
36	"minimum": -180.0,
37	"maximum": 180.0
38	}
39	]
40	},
41	"NumberNonNegative": {
42	"allOf": [
43	{
44	"$ref": "#/$defs/NumberOther"
45	},
46	{
47	"minimum": 0.0
48	}
49	]
50	},
51	"NumberOther": {
52	"$ref": "#/$defs/MyNumber"
53	},
54	"String10": {
55	"allOf": [
56	{
57	"type": "string"
58	},
59	{
60	"maxLength": 10
61	}
62	]
63	},
64	"StringPattern": {
65	"allOf": [
66	{
67	"$ref": "#/$defs/MyCharacterString"
68	},
69	{
70	"pattern": "^[abc]{3}$"
71	}
72	]
73	}
74	}
75	}

Figure 12 — Example of basic types encoded in JSON Schema

7.3.4.  Properties

7.3.4.1.  General

Requirement 12
Identifier	/req/core/properties
Included in	Requirements class 1: /req/core
Statement	A UML property shall be converted to a member of a JSON object — unless the encoding rule defines a different behavior for the type that owns the property (e.g., for enumerations, unions, and code lists).

NOTE  By default, UML properties are converted to keys within the “properties” member of the JSON Schema definition for the type that owns the property. Additional requirements may override this encoding (e.g., the type discriminator encoding of «union» properties), or augment the encoding (e.g., encoding the properties under the “properties” member of a GeoJSON-based feature).

The default result of converting a UML property, therefore, is a key within the “properties” key of the JSON Schema definition for the type that owns the property, with the key name being the name of the UML property, and the value being a JSON Schema with constraints and annotations that define the property (value type, multiplicity, etc).

The following figure and listing provide an example: Figure 13 shows a feature type with a number of properties. Figure 14 illustrates how the UML properties are represented within the “properties” of the JSON Schema that defines that type.

Figure 13 — UML type used to exemplify JSON Schema encoding of UML properties

1	{
2	"$schema": "http://json-schema.org/draft/2020-12/schema",
3	"$defs": {
4	"TypeX": {
5	"type": "object",
6	"properties": {
7	"property1": {"type": "string"},
8	"property2": {"type": "number"}
9	},
10	"required": [
11	"property1", "property2"
12	]
13	}
14	}
15	}

Figure 14 — Encoding UML properties in JSON Schema

7.3.4.2.  Value Type

Requirement 13
Identifier	/req/core/property-inline
Included in	Requirements class 1: /req/core
Statement	The value type of a UML property shall be encoded as a JSON Schema constraint, as follows:
A	If the value type of a UML property is an external type, and the JSON Schema definition of that external type is a simple JSON value type, i.e., “string”, “number”, “integer”, or “boolean”, then a “type” key shall be added to the JSON Schema definition of the property, with the simple JSON value type as value;
B	Otherwise, a “$ref” key shall be added to the JSON Schema that constrains the property. The “$ref” value shall be a reference to the JSON Schema definition of the value type, within a particular definitions schema. The reference can be absolute or relative, and typically contains a fragment identifier to identify the definition of the value type.

Examples:

• using the “$anchor” value “TypeX” as fragment identifier: https://example.org/schemas/schema_definitions.json#TypeX

• using JSON Pointer as fragment identifier: https://example.org/schemas/schema_definitions.json#/$defs/TypeX

  • NOTE: If the referenced schema is a draft 07 JSON Schema, the JSON Pointer would have to change as follows: https://example.org/schemas/schema_definitions.json#/definitions/TypeX

  NOTE  Keep in mind that the use of a fragment identifier with anchor or JSON Pointer value in $ref references can depend upon the media type with which the referenced JSON schema is published, as is explained in more detail here.

The behavior described in /req/core/property-inline covers the case of an inline encoding of the property value. That is sufficient for simple application schemas. For more complex schemas, typically ones that contain associations between feature types, it can be necessary or desired to encode property values by-reference, i.e., using links. However, multiple options exist for realizing a by-reference encoding. These options are defined in separate requirements classes — see Clause 7.8. A particular JSON Schema encoding of a given application schema needs to choose one of these options, in order to enable by-reference encoding for relevant properties.

Figure 15 — Examples of classes from two application schemas with properties that are implemented as simple JSON Schema types and as schema references

1	{
2	"$schema": "https://json-schema.org/draft/2020-12/schema",
3	"$id": "http://example.org/schema/schemaA.json",
4	"$defs": {
5	"Class1": {
6	"$anchor": "Class1",
7	"type": "object",
8	"properties": {
9	"attBoolean": {
10	"type": "boolean"
11	},
12	"role2_1": {
13	"$ref": "#/$defs/Class2"
14	}
15	}
16	},
17	"Class2": {
18	"$anchor": "Class2",
19	"type": "object",
20	"properties": {
21	"attInteger": {
22	"type": "integer"
23	}
24	}
25	}
26	}
27	}

Figure 16 — Example schema A, encoded as JSON Schema

1	{
2	"$schema": "https://json-schema.org/draft/2020-12/schema",
3	"$id": "http://example.org/schema/schemaB.json",
4	"$defs": {
5	"Class3": {
6	"$anchor": "Class3",
7	"type": "object",
8	"properties": {
9	"role1_3": {
10	"$ref": "schemaA.json#/$defs/Class1"
11	},
12	"attCharacterString": {
13	"type": "string"
14	}
15	}
16	}
17	}
18	}

Figure 17 — Example schema B, encoded as JSON Schema

This JSON object is valid against the definition of “Class1” from Figure 16:

{
  "attBoolean": true,
  "role2_1": {
    "attInteger": 2
  }
}

Figure 18

This JSON object is invalid (because “attInteger” has a string value, where an integer value is expected) against the schema from Figure 16:

{
  "attBoolean": true,
  "role2_1": {
    "attInteger": "X"
  }
}

Figure 19

7.3.4.3.  Multiplicity

Requirement 14
Identifier	/req/core/property-multiplicity
Included in	Requirements class 1: /req/core
A	If the multiplicity lower bound of a UML property is 1 or greater, and the class that owns the property is not a «union», then the property shall be listed under the “required” properties of the JSON object to which the property belongs.
B	In addition, if the multiplicity upper bound of the property is greater than 1, then the JSON Schema definition for the property shall be created as follows. The “type” of the JSON property is set to “array”, with the “items” keyword containing the JSON Schema constraints that are created to represent the value type of the property. If the multiplicity lower bound is greater than 0, it is encoded using the “minItems” keyword. If the multiplicity upper bound is not unbounded, it is encoded using the “maxItems” keyword. If the values of the property are defined to be unique (which is the default for UML properties), then that is represented by adding "uniqueItems": true.

Figure 20 — UML type used to exemplify JSON Schema encoding of multiplicity

1	{
2	"$schema": "http://json-schema.org/draft/2020-12/schema",
3	"$defs": {
4	"Type": {
5	"type": "object",
6	"properties": {
7	"property": {
8	"type": "array",
9	"minItems": 1,
10	"maxItems": 2,
11	"items": {
12	"type": "string"
13	},
14	"uniqueItems": true
15	}
16	},
17	"required": [
18	"property"
19	]
20	}
21	},
22	"$ref": "#/$defs/Type"
23	}

Figure 21 — Example for encoding multiplicity in JSON Schema

This JSON object is valid against the schema from Figure 21:

{
"property": ["a","b"]
}

Figure 22

This JSON object is invalid (because “property” has three values, which exceeds the maximum amount of allowed values) against the schema from Figure 21:

{
"property": ["a","b","c"]
}

Figure 23

NOTE  All arrays in JSON are ordered, thus that the values of a UML property are ordered is always represented, and that the values of such a property are unordered cannot be represented. However, the latter should not matter to an application that does not expect ordered values for a certain property.

7.3.4.4.  Fixed / readOnly

Requirement 15
Identifier	/req/core/property-fixed-readonly
Included in	Requirements class 1: /req/core
Statement	The JSON Schema definition of a UML property that is marked as read only or fixed shall include the “readOnly” annotation with JSON value true.

Figure 24 — UML type used to exemplify JSON Schema encoding of a readOnly property

1	{
2	"$schema": "https://json-schema.org/draft/2020-12/schema",
3	"$defs": {
4	"FeatureType1": {
5	"$anchor": "FeatureType1",
6	"type": "object",
7	"properties": {
8	"attribute": {
9	"type": "string",
10	"readOnly": true
11	}
12	}
13	}
14	}
15	}

Figure 25 — Example for encoding a readOnly property in JSON Schema

7.3.4.5.  Derived

Requirement 16
Identifier	/req/core/property-derived
Included in	Requirements class 1: /req/core
Statement	The JSON Schema definition of a UML property that is marked as derived shall include the “readOnly” annotation with JSON value true.

Figure 26 — UML type used to exemplify JSON Schema encoding of a derived property

1	{
2	"$schema": "https://json-schema.org/draft/2020-12/schema",
3	"$defs": {
4	"FeatureType2": {
5	"$anchor": "FeatureType2",
6	"type": "object",
7	"properties": {
8	"attribute": {
9	"type": "string",
10	"readOnly": true
11	}
12	}
13	}
14	}
15	}

Figure 27 — Example for encoding a derived property in JSON Schema

7.3.4.6.  Initial Value

Requirement 17
Identifier	/req/core/property-initial-value
Included in	Requirements class 1: /req/core
Statement	A UML attribute that has an initial value, is owned by a type with identity or a «DataType», and whose value type is encoded as one of the simple JSON Schema types “string”, “number”, “integer”, or “boolean”, shall be encoded as follows:
A	The JSON Schema definition of the UML attribute shall include the “default” annotation with the initial value as value.
B	The value of the annotation can have any JSON value type. The initial value shall be encoded accordingly: quoted, if the JSON Schema type is “string”; unquoted if the JSON Schema type is “number” or “integer”; and true if the JSON Schema type is “boolean” and the initial value is equal to, ignoring case, “true”; otherwise the value is false.

NOTE  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.

Figure 28 — UML type used to exemplify JSON Schema encoding of properties with initial value

1	{
2	"$schema": "https://json-schema.org/draft/2020-12/schema",
3	"$defs": {
4	"DataType": {
5	"$anchor": "DataType",
6	"type": "object",
7	"properties": {
8	"attInteger": {
9	"type": "integer",
10	"default": 1
11	},
12	"attNumber": {
13	"type": "number",
14	"default": 2.2
15	}
16	}
17	},
18	"FeatureType3": {
19	"$anchor": "FeatureType3",
20	"type": "object",
21	"properties": {
22	"attBoolean": {
23	"type": "boolean",
24	"default": true
25	},
26	"attCharacterString": {
27	"type": "string",
28	"default": "xyz"
29	}
30	}
31	}
32	}
33	}

Figure 29 — Example for encoding properties with initial value in JSON Schema

7.3.5.  Association class

Standard UML supports the concept of association class, i.e., an association that has properties. There is no native represention for association classes in JSON or JSON Schema. Association classes therefore need to be converted to “intermediate” classes, before being serialized to JSON Schema. The conversion is illustrated in the following figures, with Figure 30 showing the original conceptual model, and Figure 31 showing the conversion result.

Figure 30 — Model with association classes

Figure 31 — Association classes transformed to intermediate classes

7.3.6.  Constraints

OCL constraints can be used to enrich a conceptual model with requirements that cannot be expressed in UML alone. However, this specification does not define any requirements for converting OCL constraints to JSON Schema definitions, or to any other format with which the constraints can be checked on a JSON dataset.

7.3.7.  Conceptual model transformations

The conceptual schema may need to be transformed, in order to deal with model elements:

• that cannot be represented in a certain JSON format (e.g., a Solid — a 3D geometry type — as value for the “geometry” member of a GeoJSON feature); or

• that are not (well) supported by client software (e.g., complex attribute values for styling, processing, and filtering).

No specific model transformation requirements and recommendations are defined in this document. Examples of model transformations are given in OGC 20-012 and in the GitHub repository with model transformation rules by the INSPIRE community.

7.3.8.  Primary geometry

OGC 23-058r1 defines the concept of primary geometry:

The concept is generally applicable to feature types. Examples of data formats to which the concept applies are GeoJSON and JSON-FG. Requirements regarding the encoding of the primary geometry are defined in the according requirements classes (/req/geojson and /req/jsonfg).

In order to identify the UML property that represents the primary geometry of a feature type, the following approach is used in this specification:

• If a single (direct or inherited, but ignoring redefined) UML property of the feature type has tag “primaryGeometry” with value equal to and ignoring case “true”, then that property is the primary geometry of the feature type.

• Otherwise, if the set of (direct and inherited, but ignoring redefined) UML properties of the feature type 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 “primaryGeometry” with value equal to, ignoring case, “false”, then that property is the primary geometry of the feature type.

• Otherwise, no primary geometry is defined for the feature type.

7.3.9.  Primary temporal information

OGC 23-058r1 defines the concept of primary temporal information:

The concept is generally applicable to feature types. An example of a data format to which the concept applies is JSON-FG. Requirements regarding the encoding of primary temporal information are defined in the according requirements class (/req/jsonfg).

In order to identify the UML property that represents the primary geometry of a feature type, the following approach is used in this specification:

• A UML property that is owned by the feature type and that has tag “primaryInstant” with value equal to and ignoring case “true” is the primary-instant of the feature type.

• A UML property that is owned by the feature type and that has tag “primaryInterval” with value equal to and ignoring case:

  • “interval” is the primary-interval of the feature type.

  • “start” is the primary-interval-start of the feature type.

  • “end” is the primary-interval-end of the feature type.

7.4.1.  Common base schema

As described in the core requirements class, common base types or — for the purposes of this encoding rule — common JSON Schema definitions can be added to the schema definition of certain kinds of classes, for example, all feature types. This requirements class does not specify any such common JSON Schema definitions. As a consequence, if the types with identity defined by an application schema do not contain attributes that convey the identity of an actual object, according JSON objects cannot be identified using information from property values. Additional requirements classes, which depend on /req/plain, may add requirements regarding a common base.

7.4.2.  Implementation of ISO 19107 types

Table 8 — JSON Schema implementation of types defined by ISO 19107 for the plain JSON Schema encoding rule

7.4.3.  Identifier property

This requirements class does not define a means to add an identifier property — i.e., a UML property that is modeled with “isId” = true — to the JSON Schema encoding of a feature type, if that type does not declare such a property. The application schema would need to be transformed, in order to add an identifier property, where necessary.

7.5.1.  Identifier property

7.5.2.  Nesting feature type properties

7.6.1.  Common base schema

As described in the core requirements class, common base types or — for the purposes of this encoding rule — common JSON Schema definitions can be added to the schema definition of certain kinds of classes, for example, all feature types.

Figure 32 illustrates a feature type hierarchy, and Figure 33 shows how these feature types are encoded in JSON Schema using the common base schema. Note that the definitions of the individual feature types still state “type”: “object” in order to illustrate the place where object properties would be defined. However, such properties have been omitted in the example to avoid unnecessary complexity.

Figure 32 — Example of a feature type hierarchy in an application schema

1

{

2

  "$schema": "https://json-schema.org/draft/2020-12/schema",

3

  "$id": "http://example.org/schema/infra.json",

4

  "$defs": {

5

    "Building": {

6

      "$anchor": "Building",

7

      "allOf": [

8

        {

9

          "$ref": "#/$defs/Building_Core"

10

        },

11

        {

12

          "type": "object"

13

        }

14

      ]

15

    },

16

    "BuildingPart": {

17

      "$anchor": "BuildingPart",

18

      "allOf": [

19

        {

20

          "$ref": "#/$defs/Building_Core"

21

        },

22

        {

23

          "type": "object"

24

        }

25

      ]

26

    },

27

    "Building_Core": {

28

      "$anchor": "Building_Core",

29

      "allOf": [

30

        {

31

          "$ref": "https://geojson.org/schema/Feature.json"

32

        },

33

        {

34

          "type": "object"

35

        }

36

      ]

37

    },

38

    "Parcel": {

39

      "$anchor": "Parcel",

40

      "allOf": [

41

        {

42

          "$ref": "https://geojson.org/schema/Feature.json"

43

        },

44

        {

45

          "type": "object"

46

        }

47

      ]

48

    }

49

  }

50

}

Figure 33 — Example for encoding the common base schema for feature types

7.6.2.  Implementation of ISO 19107 types for the “geometry” member

Table 9 — JSON Schema implementation of types defined by ISO 19107, for the “geometry” member in the GeoJSON encoding rule

7.6.3.  Primary geometry

Figure 34 — Example of a feature type with an attribute designated as primary geometry

1

{

2

  "$schema": "https://json-schema.org/draft/2020-12/schema",

3

  "$defs": {

4

    "Parcel": {

5

      "$anchor": "Parcel",

6

      "allOf": [

7

        {

8

          "$ref": "https://geojson.org/schema/Feature.json"

9

        },

10

        {

11

          "type": "object",

12

          "properties": {

13

            "geometry": {

14

              "$ref": "https://geojson.org/schema/Polygon.json"

15

            }

16

          }

17

        }

18

      ]

19

    }

20

  }

21

}

Figure 35 — Example for encoding a feature type with primary geometry

7.7.1.  Common base schema

As described in the core requirements class, common base types or — for the purposes of this encoding rule — common JSON Schema definitions can be added to the schema definition of certain kinds of classes, for example, all feature types.

An example of encoding feature types with a common base schema is given in Clause 7.6.1. It can easily be adapted to match /req/jsonfg/common-base by exchanging “https://geojson.org/schema/Feature.json” with “https://beta.schemas.opengis.net/json-fg/feature.json”.

7.7.2.  Implementation of ISO 19107 types for the “place” member

Table 10 — JSON Schema implementation of types defined by ISO 19107, for the “place” member

7.7.3.  Primary geometry

Figure 36 — Example of a feature type with an attribute designated as primary place

1

{

2

  "$schema": "https://json-schema.org/draft/2020-12/schema",

3

  "$defs": {

4

    "BuildingPart": {

5

      "$anchor": "BuildingPart",

6

      "allOf": [

7

        {

8

          "$ref": "http://example.org/schema/infra.json#Building_Core"

9

        },

10

        {

11

          "type": "object",

12

          "properties": {

13

            "place": {

14

              "oneOf": [

15

                {

16

                  "type": "null"

17

                },

18

                {

19

                  "$ref": "https://beta.schemas.opengis.net/json-fg/geometry-objects.json#/$defs/Polyhedron"

20

                }

21

              ]

22

            }

23

          }

24

        }

25

      ]

26

    }

27

  }

28

}

Figure 37 — Example for encoding a feature type with primary place

7.7.4.  Primary temporal information

Figure 38 — Example of a feature type with an attribute designated as primary instant

1

{

2

  "$schema": "https://json-schema.org/draft/2020-12/schema",

3

  "$defs": {

4

    "Building_Core": {

5

      "$anchor": "Building_Core",

6

      "allOf": [

7

        {

8

          "$ref": "https://beta.schemas.opengis.net/json-fg/feature.json"

9

        },

10

        {

11

          "type": "object"

12

        }

13

      ]

14

    }

15

  }

16

}

Figure 39 — Example for encoding a feature type with primary instant

7.8.1.  Overview

Requirements class /req/core specifies an inline encoding of property values. In the case that the value type of a UML property is a type with identity (that is not implemented as a simple JSON Schema type), it can be preferable and maybe even necessary to encode the value by reference. In other cases, both options should be offered. That is similar to what the GML Application Schema encoding rules support (for further details, see OGC 07-036r1, Annex E, section E.2.4.11).

Multiple options exist for realizing the by-reference encoding of property values. A requirements class is available for each option:

• /req/by-reference-uri — by-reference encoding of property values using a plain URI (reference, i.e., an absolute or relative URI)

• /req/by-reference-link-object — by-reference encoding of property values using a link object

7.8.2.  Requirements class: basics for the by-reference encoding of property values

7.8.3.  Requirements class: by-reference encoding of property values using a plain URI reference

Figure 40 — Example of an association between two feature types, where the association roles are to be encoded by reference

The JSON Schema encoding for the example in Figure 40, using URIs to realize by-reference encoding of property values, is given in Figure 41.

1

{

2

  "$schema": "https://json-schema.org/draft/2020-12/schema",

3

  "$defs": {

4

    "Parcel": {

5

      "$anchor": "Parcel",

6

      "type": "object",

7

      "properties": {

8

        "owner": {

9

          "type": "array",

10

          "minItems": 1,

11

          "items": {

12

            "type": "string",

13

            "format": "uri-reference"

14

          },

15

          "uniqueItems": true

16

        }

17

      },

18

      "required": [

19

        "owner"

20

      ]

21

    },

22

    "Person": {

23

      "$anchor": "Person",

24

      "type": "object",

25

      "properties": {

26

        "owns": {

27

          "type": "array",

28

          "items": {

29

            "type": "string",

30

            "format": "uri-reference"

31

          },

32

          "uniqueItems": true

33

        }

34

      }

35

    }

36

  }

37

}

Figure 41 — Example for encoding association roles by-reference using URIs

This JSON object is valid against the schema definition of “Parcel” from Figure 41:

{
  "owner": ["http://example.org/Person/d024i42sl"]
}

Figure 42

7.8.4.  Requirements class: by-reference encoding of property values using a link object

The JSON Schema encoding for the example in Figure 40, using link objects to realize by-reference encoding of property values, is given in Figure 43.

1

{

2

  "$schema": "https://json-schema.org/draft/2020-12/schema",

3

  "$defs": {

4

    "Parcel": {

5

      "$anchor": "Parcel",

6

      "type": "object",

7

      "properties": {

8

        "owner": {

9

          "type": "array",

10

          "minItems": 1,

11

          "items": {

12

            "$ref": "https://register.geostandaarden.nl/jsonschema/uml2json/0.1/schema_definitions.json#/$defs/LinkObject"

13

          },

14

          "uniqueItems": true

15

        }

16

      },

17

      "required": [

18

        "owner"

19

      ]

20

    },

21

    "Person": {

22

      "$anchor": "Person",

23

      "type": "object",

24

      "properties": {

25

        "owns": {

26

          "type": "array",

27

          "items": {

28

            "$ref": "https://register.geostandaarden.nl/jsonschema/uml2json/0.1/schema_definitions.json#/$defs/LinkObject"

29

          },

30

          "uniqueItems": true

31

        }

32

      }

33

    }

34

  }

35

}

Figure 43 — Example for encoding association roles by-reference using link objects

This JSON object is valid against the schema definition of “Parcel” from Figure 43:

{
  "owner": [
    {
      "title": "John Doe",
      "href": "http://example.org/Person/d024i42sl"
    }
  ]
}

Figure 44

7.9.1.  Overview

Application schemas have two ways of using types with stereotype «union».

• According to ISO 19103:2015, a «union» type consists “of one and only one of several alternative datatypes (listed as member attributes). This is similar to a discriminated union in many programming languages”. According to this definition, only the types of the UML attributes defined for a «union» are of interest.

• In practice, unions defined in application schemas are also used differently, defining a choice between a number of options, where each option is modeled as a UML attribute. In other words, the attribute itself has meaning — not just its value type. Multiple options can have the same value type. Options can have different maximum multiplicity (especially greater than 1). The UML-to-GML application schema encoding rules support this way of using unions (see OGC 07-036r1, section E.2.4.10).

The following sections document requirements classes for union encodings that support these two approaches.

7.9.2.  Requirements class: JSON Schema encoding for unions representing type discriminators

The result of applying this encoding to the unions from Figure 45 is shown in Figure 46.

Figure 45 — Example of type discriminator unions

1

{

2

  "$schema": "http://json-schema.org/draft/2020-12/schema",

3

  "$defs": {

4

    "Union_TypeDiscriminator": {

5

      "oneOf": [

6

        {

7

          "type": [

8

            "string",

9

            "integer"

10

          ]

11

        },

12

        {

13

          "$ref": "https://geojson.org/schema/Point.json"

14

        }

15

      ]

16

    },

17

    "Union_TypeDiscriminator_OtherTypes": {

18

      "oneOf": [

19

        {

20

          "$ref": "https://geojson.org/schema/LineString.json"

21

        },

22

        {

23

          "$ref": "https://geojson.org/schema/Point.json"

24

        }

25

      ]

26

    },

27

    "Union_TypeDiscriminator_SimpleTypes": {

28

      "type": [

29

        "string",

30

        "integer"

31

      ]

32

    }

33

  }

34

}

Figure 46 — Example of a JSON Schema for unions, encoding them as type discriminators

7.9.3.  Requirements class: JSON Schema encoding for unions representing property choices

The result of applying this encoding to the union from Figure 47 is shown in Figure 48.

Figure 47 — «union» example

1

{

2

  "$schema": "http://json-schema.org/draft/2020-12/schema",

3

  "$defs": {

4

    "UnionA": {

5

      "type": "object",

6

      "properties": {

7

        "option1": {

8

          "type": "string"

9

        },

10

        "option2": {

11

          "type": "number"

12

        }

13

      },

14

      "additionalProperties": false,

15

      "minProperties": 1,

16

      "maxProperties": 1

17

    }

18

  },

19

  "$ref": "#/$defs/UnionA"

20

}

Figure 48 — Example of a JSON Schema for a «union» class, representing the property choice using "minProperties" and "maxProperites"

This JSON object is valid against the schema:

{
  "option1": "x"
}

Figure 49

This JSON object is invalid (because “option2” has a string value, rather than a numeric value) against the schema:

{
  "option2": "x"
}

Figure 50

7.10.1.  Overview

This specification defines three approaches for encoding the values of properties that have a «CodeList» as value type:

• using a simple literal value, e.g., a string or number that represents a code,

• using a URI as code value, and

• using a link object to link to a code representation.

The following sections document requirements classes for code list encodings that support these three approaches. All of them inherit requirements from a common requirements class, which is defined in Clause 7.10.2.

7.10.2.  Requirements class: Basic JSON Schema encoding for code lists

Figure 51 — Example of a «CodeList» type with tagged value 'codeList'

1

{

2

  "$schema": "http://json-schema.org/draft/2020-12/schema",

3

  "$defs": {

4

    "SomeCodelist": {

5

      ...

6

      "codeList": "http://example.org/codelists/SomeCodelist",

7

      ...

8

    }

9

  }

10

}

Figure 52 — Example of the basic JSON Schema encoding of a «CodeList» type with tagged value 'codeList'

7.10.3.  Requirements class: JSON Schema encoding for code lists — literal

The literal encoding type is one of the types from ISO 19103, which are implemented as a simple JSON Schema type — see Table 6 in Clause 7.3.3.8.

Figure 53 — Example of «CodeList» types

1

{

2

  "$schema": "http://json-schema.org/draft/2020-12/schema",

3

  "$defs": {

4

    "CodelistNumeric": {

5

      "type": "number"

6

    },

7

    "CodelistString": {

8

      "type": "string"

9

    }

10