data-models

OpenActive Data Models

Data models used to drive the OpenActive validator and developer documentation.

Introduction

This library provides all the JSON representations of the models in the versions/<version>/models directory. It is capable of storing multiple versions of the spec.

API

The library provides various exports:

getExamples([version])

Returns a list of examples relating to the specification version supplied.

Each object in the list should contain the following keys:

name - A human-readable name describing the example.
file - The file the example is in.

Example

const { getExamples } = require('@openactive/data-models');

const examples = getExamples('2.0');

// [
//   {
//     "file": "event_example_1.json",
//     "name": "Example Event"
//   },
//   // ...
// ]

getExamplesWithContent([version])

Returns a list of examples relating to the specification version supplied, that includes the JSON content of these examples.

Each object in the list should contain the following keys:

name - A human-readable name describing the example.
file - The file the example is in.
data - The JSON data of the example file.

Example

const { getExamplesWithContent } = require('@openactive/data-models');

(async () => {
  const examples = await getExamplesWithContent('2.0');

  // [
  //   {
  //     "file": "event_example_1.json",
  //     "name": "Example Event",
  //     "data": { ... }
  //   },
  //   // ...
  // ]
})();

getFullyQualifiedProperty(name [, version [, contexts]])

Returns a resolved version of a property, indicating its namespace, prefix and alias. It will by default insert the OpenActive context for the provided specification version at the top of the context tree.

Example

const { getFullyQualifiedProperty } = require('@openactive/data-models');

let info = getFullyQualifiedProperty('type');

// {
//   "prefix": null,
//   "namespace": null,
//   "label": "@type",
//   "alias": "type",
// }

let info = getFullyQualifiedProperty('meetingPoint', '2.0');

// {
//   "prefix": "oa",
//   "namespace": "https://openactive.io/",
//   "label": "meetingPoint",
//   "alias": "meetingPoint",
// }

let info = getFullyQualifiedProperty('schema:name', '2.0');

// {
//   "prefix": "schema",
//   "namespace": "https://schema.org/",
//   "label": "name",
//   "alias": null,
// }

let info = getFullyQualifiedProperty('beta:field', '2.0');

// {
//   "prefix": null,
//   "namespace": null,
//   "label": "beta:field",
//   "alias": null,
// }

getMetaData([version])

Returns the meta data relating to the specification version supplied.

The meta data should contain the following keys:

defaultPrefix - The default prefix that is used in the @vocab field of the OpenActive JSON-LD definition.
openActivePrefix - The prefix used for OpenActive fields
contextUrl - The URL that the JSON context of this specification is published at
specUrl - The URL that the human-readable version of this specification is published at
defaultActivityLists - An array of activity list URLs that accompany this spec
baseGraph - A base object used when generating the @graph property of the OpenActive JSON-LD definition.
keywords - A map of aliases for JSON-LD keywords.
namespaces - A map of prefixes to namespaces used in the OpenActive JSON-LD definition.
feedConfigurations - A map of feed configurations, to be used by the Dataset Site generators.

Example

const { getMetaData } = require('@openactive/data-models');

const metaData = getMetaData('2.0');

// {
//   "defaultPrefix": "schema",
//   "openActivePrefix": "oa",
//   "contextUrl": "https://openactive.io/",
//   "specUrl": "https://openactive.io/modelling-opportunity-data/EditorsDraft/",
//   "defaultActivityLists": [
//     "https://openactive.io/activity-list"
//   ],
//   "baseGraph": {},
//   "keywords": {
//     "type": "@type",
//     "id": "@id"
//   },
//   "namespaces": {
//     "oa": "https://openactive.io/",
//     "dc": "http://purl.org/dc/terms/",
//     "owl": "http://www.w3.org/2002/07/owl#",
//     "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
//     "rdfa": "http://www.w3.org/ns/rdfa#",
//     "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
//     "schema": "https://schema.org/",
//     "skos": "http://www.w3.org/2004/02/skos/core#",
//     "xsd": "http://www.w3.org/2001/XMLSchema#",
//     "pending": "https://pending.schema.org/"
//   }
// }

loadModel(modelName [, version])

Returns the model definition, augmented based on model inheritance, for a particular version of the spec.

Example

const { loadModel } = require('@openactive/data-models');

// Returns the latest version of this model
const eventModel = loadModel('Event');

// Returns the 2.0 version of this model
const eventModel2 = loadModel('Event', '2.0');

getModels( [version] )

Returns a map of raw model definitions for a particular version of the spec.

Example

const { getModels } = require('@openactive/data-models');

// Returns the latest version of the models map
const models = getModels();

// Returns the 2.0 version of  the models map
const models2 = getModels('2.0');

getProperties( [version] )

Returns a Set containing the fully qualified property names within the version

Example

const { getProperties } = require('@openactive/data-models');

// Returns the latest version of the properties Set
const models = getProperties();

// Returns the 2.0 version of the properties Set
const models2 = getProperties('2.0');

getSchemaOrgVocab()

Returns the bundled JSON-LD version of the schema.org vocabulary.

versions

A hash of available versions. This includes some named aliases. You can pass the keys of this hash to any of the above methods in the version parameter.

Example

const { versions } = require('@openactive/data-models');

// {
//   "latest": "2.x",
//   "2.0": "2.x"
// }

Development

Getting started

$ git clone [email protected]:openactive/data-models.git
$ cd data-models
$ npm install

Running tests

This project uses Jasmine for its tests. All spec files are located alongside the files that they target.

To run tests locally, run:

$ npm test

The test run will also include a run of eslint. To run the tests without these, use:

$ npm run test-no-lint

Adding models

Add new models to the versions/models directory.

Find more on the models, see the model reference

Releasing

To release after pushing changes to git run the following:

npm test - check tests pass
npm version patch - to bump the patch version (see semver)
npm publish - to publish to npm
git push - to push the repo, as npm will have created git tags with the last command that need to be pushed
Redeploy data-model-validator-site in Heroku, and it will auto update (for patch and minor version bumps only, major versions are breaking changes by definition so require code changes to the other projects).

This site is open source. Improve this page.