Model Configuration

In sapi-nt, a model is a data model, or schema, which characterises the data which is stored in the underlying store, and the format in which it will be represented in your application’s API. Model specs have a type value of model.

A well defined model is necessary for many of sapi-nt’s features to function, however it does not always need to be comprehensive. Depending on the size and complexity of the data set you want to expose, you may choose to write a complete or partial model by hand, or use a tool like model-spec to perform large scale conversions on an entire ontology.

Model specs represent a branching, tree-like structure of connected classes, or types, similar to a JSON schema. As such they are intended to simplify the rich world of RDF data into a compact and predictable format, not to precisely replicate the complexity of formats like OWL. The concepts of classes and properties in model specs are similar to those in OWL, but not identical.

You can define a model with a name value of defaultModel to declare it as the default spec of this type. If you do, sapi-nt will use that model anywhere one is required but not specified explicitly.

Note

You should usually define just one model for your sapi-nt application, and give it the name defaultModel, since many sapi-nt features rely on the presence of a default model spec.

Structure

Model specs are comprised by the overarching characteristics of the model, its classes and their properties. These are known as “class specs” and “property specs”, but they cannot be defined separately from the model.

A model spec can have the following properties:

Property	Meaning
`prefixes`	An object mapping short form keys to URI values, which defines a prefix mapping for the model.
`prefixsrc`	A raw turtle string containing prefix mappings for the model. Can be combined with `prefixes`.
`showLangTags`	Determines whether to render language tagged strings as objects with separate value and language fields in JSON results.
`classes`	A list of class specs belonging to the model.
`properties`	A list of “global” property specs which can be referenced by URI elsewhere in the model.

Whenever you define a view spec, you may set the showLangTags property on that view to override the value in the model spec.

Prefix Mapping

The prefix mapping defined in the default model spec has many uses for both API authors and consumers.

The prefix mapping is applied to sapi-nt API responses that are presented in RDF formats, and some request query parameters that accept URI values can also accept URIs in compact prefixed form.

You can use the prefix mapping that you define in the model to write other URIs in the model, such as those of classes and properties, in compact form. Furthermore, many of the URI values that you can set in other spec files can be shortened in the same way.

Property

Properties are named resources which define RDF predicates that exist on instances of certain classes. Properties are uniquely identified by their URIs.

A property spec can have the following properties:

Property	Meaning	Default
`prop`	The URI which identifies the property.
`name`	A name which the property can be referenced by. If not given, a name will be derived from the URI.
`type`	The URI of a generic datatype, object type, or class in the model which the property’s values belong to.
`kind`	The type of property (`object` or `datatype`), as in OWL.
`valueBase`	The leading part of a URI which is shared across all values of this property.
`nested`	A nested list of properties which comprise an anonymous class of which this property’s values are instances.
`filterable`	If true, the API will allow users to request filters on the property. Otherwise, it will not.	`true`
`textSearch`	Configures text search properties. By default the text search is disabled.	`false`
`excludeValue`	A list of values to be excluded from any results which evaluate the property.
`optional`	If true, the property may not exist on some instances of the containing class. Otherwise, it is expected to take at least one value.	`false`
`multi`	If true, the property may take any number of values. Otherwise, it is expected to take at most one value.	`false`
`unique`	Determines whether the property is uniquely valued or not.	`false`
`external`	Boolean flag denoting that the property is evaluated externally and is not part of the data set.	`false`
`comment`	A brief description of the property, for documentation purposes.

However, property specs can also be written simply as strings, which denote their prop value. In this case, all of the other attributes will take empty or default values.

If a property with the same URI as a class property is defined in the properties list of the model, any attributes which are not set on the class property take the values of those on the global property. If certain properties, such as rdfs:label, are used on many classes, you can use this method to prevent repetition.

The default values of these properties can be configured by setting the sapi-nt.defaults.spec.property options in your application configuration.

Text Search

The textSearch field configures the text search options on a property and is necessary only if multi-property index is configured. The configuration can be given in the following forms:

Form	Usage	Default
Boolean	`true` to enable property-specific text search on this property using the property name in the text query, `false` to disable.	`false`
String	The name of the property to be used in the text search.	`{property name}`
Object	A nested configuration object for more specific configuration options.

The nested configuration object can have the following properties:

Property	Meaning	Default
`name`	The name of the property to be used in the text search.	`{property name}`
`supported`	`true` to enable text searches, `false` to disable.	`false`

Union Property Ranges

You can specify a range (type) for a property that is comprised by the union of multiple data types by setting the type value to be an array of those data types. You can only do this for datatype properties, ie. those which have only literal values.

Union data types can be used where there is some mixture of data types in the data, for example where xsd:dates and xsd:dateTimes have both been used on the same property.

When a filter is applied on a property with a union range, sapi-nt will attempt to cast the values in the data set to match the type of the filter value. Note that this will usually be less efficient than a direct comparison, and so should not be used on properties where indexing and performance are critical to the functioning of the API. In that case, it may be more appropriate to simply define the property without any type value.

Value Base

The valueBase is used by sapi-nt to infer URI values from simple request parameters. For example, a filter parameter with a value of Concept on a property whose valueBase is skos: will be automatically concatenated as skos:Concept.

On classes, the valueBase denotes a value base which should be applied to all properties whose type is a reference to that class (unless they already have a valueBase).

Class

Classes are named resources which define the shared characteristics of their instances. Most importantly, they define which properties are expected to have values on those instances. Classes are uniquely identified by their URIs.

Classes often correspond to rdf:type values in the data set, but this is not necessary.

A class spec can have the following properties:

Property	Meaning
`class`	The URI that identifies the class.
`valueBase`	The leading part of a URI which is shared across all instances of the class.
`comment`	A brief description of the class, for documentation purposes.
`scheme`	The URI of a concept scheme which instances of the class belong to, for documentation purposes.

Example

name: defaultModel
type: model
prefixes:
  rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns#
  rdfs: http://www.w3.org/2000/01/rdf-schema#
  owl: http://www.w3.org/2002/07/owl#
  xsd: http://www.w3.org/2001/XMLSchema#
  geo: http://www.w3.org/2003/01/geo/wgs84_pos#
  lu-c: http://training.epimorphics.com/transport/london-underground/connection/
  lu-l: http://training.epimorphics.com/transport/london-underground/line/
  lu-s: http://training.epimorphics.com/transport/london-underground/station/
  metro: http://training.epimorphics.com/transport/def/metro/
  qb: http://purl.org/linked-data/cube#
  passengers: http://training.epimorphics.com/transport/def/passenger-count/
  museum: http://training.epimorphics.com/culture/london/museum/
  dbpedia: http://dbpedia.org/ontology/
classes:
- class: metro:UndergroundStation
  properties:
    - prop: rdfs:label
      type: xsd:string
    - prop: metro:incomingConnection
      optional: true
      type: metro:TransportConnection
    - prop: metro:outgoingConnection
      optional: true
      type: metro:TransportConnection
    - prop: metro:nearbyTo
      optional: true
- class: metro:TransportConnection
  properties:
    - rdfs:label
    - metro:fromStop
    - metro:toStop
    - prop: metro:onLine
      valueBase: "lu-l:"
- class: metro:UndergroundLine
  properties:
    - rdfs:label
    - metro:terminal