Model file format

Model

Each model should have a file corresponding to it in src/<version>/models. The name of the file should correspond to the name of the object the model is describing.

e.g. for model Event, the file name should be Event.json.

Properties

type

The type of object that this model describes. The name of the file should correspond to the name of the object the model is describing.

{
  "@type": "Event"
}

subClassOf

If this model is the subclass of another model or an external class for which a local model does not exist, this can be referenced here.

When calling loadModel, all of the parent model properties will be inherited.

{
  "@type": "BabyChanging",
  "subClassOf": "#LocationFeatureSpecification"
}

{
  "@type": "FacilityUse",
  "subClassOf": "https://schema.org/Product"
}

derivedFrom

A url pointing to any external objects that this model derives from.

Note this cannot be set when subClassOf is set to an external class.

{
  "derivedFrom": "https://schema.org/Event"
}

hasId

A boolean indicating whether this model has a JSON-LD @id property, which must always be in URL format.

{
  "hasId": true
}

sampleId

An example @id.

{
  "sampleId": "https://api.example.com/events/12345"
}

isJsonLd

Whether the this model is JSON-LD (defaults to true)

{
  "isJsonLd": false
}

requiredFields

An array of field names that are REQUIRED in the specification. This should only include fields that are explicitly mentioned in the OpenActive spec.

{
  "requiredFields": [
    "id",
    "@context",
    "type"
  ]
}

requiredOptions

Where one of a collection of fields are required (e.g. an Event must have a schema:startDate or oa:eventSchedule), this can be specified here.

{
  "requiredOptions": [
    {
      "description": [
        "While these properties are marked as optional, a data publisher must provide either a schema:startDate or specify a oa:eventSchedule for an event."
      ],
      "options": [
        "startDate",
        "eventSchedule"
      ]
    }
  ]
}

recommendedFields

An array of field names that are RECOMMENDED in the specification. This should only include fields that are explicitly mentioned in the OpenActive spec.

{
  "recommendedFields": [
    "description",
    "image",
    "organizer"
  ]
}

inSpec

An array of field names that are defined in the specification. This should only include fields that are explicitly mentioned in the OpenActive spec.

This MUST include ALL required, recommended and optional fields.

{
  "inSpec": [
    "id",
    "@context",
    "name"
  ]
}

notInSpec

An array of field names that are not defined for a particular model, where it inherits fields from a parent class.

{
  "notInSpec": [
    "eventSchedule"
  ]
}

commonTypos

An key-value object of common typos for field names.

{
  "commonTypos": {
    "offer": "offers"
  }
}

fields

A key-value object of Fields (see below).

{
  "fields": {
    "description": {
      "fieldName": "description",
      "requiredType": "https://schema.org/Text",
      "example": "An fast paced game that incorporates netball, handball and football.",
      "description": [
        "A free text description of the event"
      ]
    }
  }
}

description

TODO

namedExamples

TODO

Field

Properties

fieldName

The name of the field. In the Model.fields or Model.betaFields layout, this should match the key of the field.

{
  "fieldName": "description"
}

model

The name of the model this field should conform to. This should reference another model that we have a local definition for.

{
  "model": "#Event"
}

If this is an array of models, you can represent it as below:

{
  "model": "ArrayOf#Event"
}

alternativeModels

Alternative models this field should conform to. This should reference another model that we have a local definition for.

{
  "model": "#Event",
  "alternativeModels": [
    "ArrayOf#Event"
  ]
}

requiredType

The schema.org type this field should conform to.

{
  "requiredType": "https://schema.org/url"
}

If this is an array of values, you can represent it as below:

{
  "requiredType": "ArrayOf#https://schema.org/url"
}

alternativeTypes

Alternative schema.org types this field can conform to.

{
  "requiredType": "https://schema.org/url",
  "alternativeTypes": [
    "ArrayOf#https://schema.org/url"
  ]
}

minDecimalPlaces

The minimum number of decimal places this field should have.

{
  "fieldName": "longitude",
  "sameAs": "https://schema.org/longitude",
  "requiredType": "https://schema.org/Number",
  "minDecimalPlaces": 3,
  "example": -0.083437,
  "description": [
    "The longitude of a location. For example -0.083437 (WGS 84)."
  ]
}

maxDecimalPlaces

The maximum number of decimal places this field should have.

{
  "fieldName": "price",
  "sameAs": "https://schema.org/price",
  "requiredType": "https://schema.org/Number",
  "example": 33.00,
  "maxDecimalPlaces": 2,
  "description": [
    "The offer price of the activity.",
    "This price should be specified without currency symbols and as a floating point number with two decimal places.",
    "The currency of the price should be expressed in the priceCurrency field."
  ]
}

minValueInclusive

The minimum value of a number, inclusive.

"repeatCount": {
  "fieldName": "repeatCount",
  "sameAs": "https://pending.schema.org/repeatCount",
  "requiredType": "https://schema.org/Integer",
  "example": 3,
  "description": [
    "Defines the number of times a recurring Event will take place."
  ],
  "minValueInclusive": 1
},

valueConstraint

A specific constraint on the value of the property.

Available constraints are:

`UriTemplate`

A RFC 6570 compliant Uri Template represented as a string.

{
  "fieldName": "idTemplate",
  "sameAs": "https://openactive.io/idTemplate",
  "requiredType": "https://schema.org/Text",
  "example": "https://api.example.org/session-series/123/{startDate}",
  "description": [
    "An RFC 6570 compliant URI template that can be used to generate a unique identifier (`@id`) for every event described by the schedule. This property is required if the data provider is supporting third-party booking via the Open Booking API, or providing complimentary individual `subEvent`s."
  ],
  "valueConstraint": "UriTemplate"
},

`UUID`

A lowercase universally unique identifier represented as a string. RFC 4122 Section 3 requires that UUID characters be generated in lower case.

{
  "fieldName": "identifier",
  "sameAs": "https://schema.org/identifier",
  "requiredType": "https://schema.org/Text",
  "example": "123e4567-e89b-12d3-a456-426614174000",
  "description": ["The Order UUID of the Order, OrderQuote or OrderProposal, which is required within the Orders feed."],
  "valueConstraint": "UUID"
},

allowReferencing

Allow the property value to be an IRI referencing the @id of a JSON-LD object in another feed.

"superEvent": {
  "fieldName": "superEvent",
  "sameAs": "https://schema.org/superEvent",
  "model": "#Event",
  "allowReferencing": true
},

requireReferencingInValidationMode

The value of this property must be an IRI in the specified validation modes.

"orderedItem": {
  "fieldName": "orderedItem",
  "sameAs": "https://schema.org/orderedItem",
  "model": "#Event",
  "allowReferencing": true,
  "requireReferencingInValidationMode": ["C1Request", "C2Request", "PRequest", "BRequest", "OrdersFeed"]
},

requiredContent

If this property must be set to a specific value, this can be specified here.

{
  "fieldName": "type",
  "requiredType": "https://schema.org/Text",
  "requiredContent": "Event",
  "description": "",
  "example": "Event"
}

description

An array of strings (one per paragraph), describing this field.

{
  "description": [
    "A URL to a web page (or section of a page) that describes the event."
  ]
}

example

An example value of this field, for documentation.

{
  "fieldName": "url",
  "requiredType": "https://schema.org/url",
  "description": [
    "A URL to a web page (or section of a page) that describes the event."
  ],
  "example": "https://example.com/event/1234"
}

options

If this property must be set to a specific value picked from a list (e.g. an enum), the list values can be specified here.

{
  "fieldName": "eventStatus",
  "requiredType": "https://schema.org/url",
  "description": [
    "The status of an event. Can be used to indicate rescheduled or cancelled events"
  ],
  "options": [
    "https://schema.org/EventCancelled",
    "https://schema.org/EventPostponed",
    "https://schema.org/EventRescheduled",
    "https://schema.org/EventScheduled"
  ],
  "example": "https://schema.org/EventScheduled"
}

inheritsTo

If this property allows an object to pass values down for inheritance by the child, you can specify this in a number of ways.

If all fields are inheritable:

{
  "fieldName": "subEvent",
  "inheritsTo": "*"
}

To specify a blacklist of fields:

{
  "fieldName": "subEvent",
  "inheritsTo": {
    "exclude": ["id", "identifier", "subEvent", "superEvent"]
  }
}

To specify a whitelist of fields:

{
  "fieldName": "subEvent",
  "inheritsTo": {
    "include": ["name", "description", "startDate", "endDate"]
  }
}

exclude takes precedence over include.

inheritsFrom

If this property allows an object to inherit properties from it, you can specify this in a number of ways.

If all fields are inheritable:

{
  "fieldName": "superEvent",
  "inheritsFrom": "*"
}

To specify a blacklist of fields (anything not in this list will be inheritable):

{
  "fieldName": "superEvent",
  "inheritsFrom": {
    "exclude": ["id", "identifier", "subEvent", "superEvent"]
  }
}

To specify a whitelist of fields (anything not in this list will not be inheritable):

{
  "fieldName": "subEvent",
  "inheritsFrom": {
    "include": ["name", "description", "startDate", "endDate"]
  }
}

exclude takes precedence over include.

deprecationGuidance

If this field has been deprecated, deprecationGuidance must be provided:

{
  "fieldName": "ageRange",
  "deprecationGuidance": "Use `ageRestriction` instead of `ageRange` within the `Offer` for cases where the `Offer` is age restricted."
}

Note that deprecation is different from schema.org's supersededBy, as deprecation can occur for a specific use of the property within a particular type rather than the entire property.

Namespace resolution

sameAs is REQUIRED, and must reflect the fieldName within the relevant namespace.

DEPRECATED Namespace resolution

Although the section below still reflects the inner workings of the validator, sameAs is now REQUIRED to remove ambiguity and make the model files easier to parse by various tools. It is expected that future versions of the OpenActive validator library will remove the namespace resolution logic specified below, and instead use the sameAs value provided.

For each field within the model, the rules of resolution are thus:

IF sameAs is set on the field, use the namespace in there (see example) (the activity field is defined in the OA namespace, but Event is schema.org)
ELSE IF derivedFrom is set for the model, use the namespace in there (see example
ELSE IF derivedFrom is set for a model further up the hierarchy as is specified via subClassOf, use the namespace in there
ELSE IF subClassOf at the base of the hierarchy is an external class, use the namespace in there
ELSE assume the field is in the OA namespace

If the same field has been defined in two different namespaces (e.g. in both "schema:" and "oa:"), the oa.jsonld file would not be able to be generated, and the unit tests produce the error "namespaces should not have fields in multiple namespaces".

Where the sameAs namespace is the same as the derivedFrom namespace, the use of sameAs is redundant.

Files

MODELS.md

Latest commit

History

MODELS.md

File metadata and controls

Model file format

Model

Properties

type

subClassOf

derivedFrom

hasId

sampleId

isJsonLd

requiredFields

requiredOptions

recommendedFields

inSpec

notInSpec

commonTypos

fields

description

namedExamples

Field

Properties

fieldName

model

alternativeModels

requiredType

alternativeTypes

minDecimalPlaces

maxDecimalPlaces

minValueInclusive

valueConstraint

UriTemplate

UUID

allowReferencing

requireReferencingInValidationMode

requiredContent

description

example

options

inheritsTo

inheritsFrom

deprecationGuidance

Namespace resolution

DEPRECATED Namespace resolution

`UriTemplate`

`UUID`