https://github.com/openactive/data-models
Data models used to drive OpenActive validator and developer documentation
https://github.com/openactive/data-models
validators
Last synced: 8 months ago
JSON representation
Data models used to drive OpenActive validator and developer documentation
- Host: GitHub
- URL: https://github.com/openactive/data-models
- Owner: openactive
- License: mit
- Created: 2018-07-18T11:20:06.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2025-05-27T13:26:54.000Z (10 months ago)
- Last Synced: 2025-07-06T17:05:12.194Z (9 months ago)
- Topics: validators
- Language: JavaScript
- Homepage: http://openactive.io/data-models/
- Size: 1.34 MB
- Stars: 1
- Watchers: 7
- Forks: 2
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenActive Data Models
Data models used to drive the OpenActive validator and developer documentation.
[](https://github.com/openactive/data-models/actions/workflows/npm-test.yml)
[](https://snyk.io/test/github/openactive/data-models)
## Introduction
This library provides all the JSON representations of the models in the `versions//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
```js
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
```js
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
```js
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
```js
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
```js
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
```js
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
```js
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
```js
const { versions } = require('@openactive/data-models');
// {
// "latest": "2.x",
// "2.0": "2.x"
// }
```
## Development
### Getting started
```shell
$ git clone git@github.com:openactive/data-models.git
$ cd data-models
$ npm install
```
### Running tests
This project uses [Jasmine](https://jasmine.github.io/) for its tests. All spec files are located alongside the files that they target.
To run tests locally, run:
```shell
$ npm test
```
The test run will also include a run of [eslint](https://eslint.org/). To run the tests without these, use:
```shell
$ npm run test-no-lint
```
### Adding models
Add new models to the `versions/models` directory.
Find more on the models, see the [model reference](MODELS.md)
### 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](https://docs.npmjs.com/getting-started/semantic-versioning))
- `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).