Schema.org Adapter

Type aliases

Context

Context: Record<string, ContextEntry>

FilterObject

FilterObject: { fromVocabulary?: string | string[]; fromVocabularyExclude?: string | string[]; isSuperseded?: boolean; schemaModule?: SchemaModule | SchemaModule[]; schemaModuleExclude?: SchemaModule | SchemaModule[]; strictMode?: boolean; termType?: TermTypeLabelValue | TermTypeLabelValue[]; termTypeExclude?: TermTypeLabelValue | TermTypeLabelValue[] }

SDO-Adapter provides various query-functions that accept a FilterObject as optional parameter to narrow down the results. These query-functions typically return arrays of IRIs for vocabulary terms. You could for example pass a filter to .getAllClasses() to retrieve only classes from a specific vocabulary. You could pass a filter to .getRanges() to get only the ranges of a property that are enumerations (without classes or data-types). The optional attributes for a filter are described below. Keep in mind that there are no default values for these filters, that means that not using a certain attribute in the FilterObject results in not using that characteristic for filtering at all.

example

// following filter can be passed to a function to retrieve only classes and enumerations that are from schema.org and are not superseded
{
  isSuperseded: false,
  fromVocabulary: ["https://schema.org/"],
  termType: [
    "Class",
    "Enumeration"
  ]
}

// following filter can be passed to a function to retrieve only terms that are superseded
{
  isSuperseded: true
}

Type declaration

Optional fromVocabulary?: string | string[]

Namespaces for vocabularies (e.g. "https://schema.org/") can be passed here, which matches only vocabulary terms that use any of the given namespaces in their IRI. You can check the namespaces and corresponding identifiers (e.g. "schema") used by an SDO-Adapter instance with .getVocabularies(). It is also possible to get the corresponding namespace of Term instance with .getVocabulary().
Optional fromVocabularyExclude?: string | string[]

Namespaces for vocabularies (e.g. "https://schema.org/") can be passed here to sort out vocabulary terms with the given namespaces in their IRI. This filter is the opposite of fromVocabulary and they rule each other out (only one of them can be used at the same time).
Optional isSuperseded?: boolean

If true, only superseded vocabulary terms are matched. If false, only vocabulary terms that are NOT superseded are matched.
Optional schemaModule?: SchemaModule | SchemaModule[]

Schema module identifiers can be passed here, which matches only vocabulary terms from schema.org that are from any of the given schema modules. This filter applies only to schema.org terms, terms from other vocabularies are not filtered in/out. More information about the schema modules can be found in Organization of Schemas - Hosted Sections
Optional schemaModuleExclude?: SchemaModule | SchemaModule[]

Schema module identifiers can be passed here to sort out vocabulary terms from the given schema modules. This filter is the opposite of schemaModule and they rule each other out (only one of them can be used at the same time). More information about the schema modules can be found in Organization of Schemas - Hosted Sections
Optional strictMode?: boolean

The strictMode defines how IRIs of non-present terms (e.g. a Term that is linked by a vocabulary node, but is itself not present in the current vocabulary) should be handled. Some filters (e.g. termType) require term instances to do their checks. If the strictMode is true (default), then such IRIs are filtered out. If the strictMode is false then those IRIs are kept in the result.
Optional termType?: TermTypeLabelValue | TermTypeLabelValue[]

Term types can be passed here, which matches only vocabulary terms that have any of the given term types. Class and Enumeration are strictly differentiated here.
Optional termTypeExclude?: TermTypeLabelValue | TermTypeLabelValue[]

Term types can be passed here to sort out vocabulary terms from the given term types. Class and Enumeration are strictly differentiated here. This filter is the opposite of termType and they rule each other out (only one of them can be used at the same time).

OutputIRIType

OutputIRIType: "Compact" | "Absolute"

Defines the format in which the IRI results from functions should be returned. This option can be set for the SDO-Adapter on initialization, which becomes the standard (default = "Compact"). After the initialization it is also possible to pass this option to some API-functions to get IRIs in a different format. The options are as follows:

"Compact": The resulting IRIs are given in compact form, e.g. "schema:Hotel"
"Absolute": The resulting IRIs are given in absolute form, e.g. "https://schema.org/Hotel"

ParamObjCreateSdoAdapter

ParamObjCreateSdoAdapter: { commit?: string; defaultFilter?: FilterObject; equateVocabularyProtocols?: boolean; onError?: ErrorFunction; outputFormat?: OutputIRIType; schemaHttps?: boolean; schemaVersion?: string; vocabularies?: (Vocabulary | string)[] }

A parameter object to create a new SDO Adapter instance. All attributes of this object are optional (as well as the parameter object itself) and describe a certain setting that should be used for the created SDO Adapter.

example

{
  schemaVersion: "latest",
  vocabularies: ["https://raw.githubusercontent.com/semantifyit/schema-org-adapter/master/tests/resources/data/vocabularies/vocabulary-animal.json"],
  commit: "9a3ba46",
  schemaHttps: true,
  equateVocabularyProtocols: true,
  outputFormat: "Compact",
  defaultFilter: {
   schemaModuleExclude: ["attic", "meta"],
   isSuperseded: false
  },
  onError: (e) => {
    console.error(e);
  }
}

Type declaration

Optional commit?: string

The commit string from https://github.com/schemaorg/schemaorg which is taken as source for the SDO Adapter (if not given, the latest commit of our fork at https://github.com/semantifyit/schemaorg is taken). Use this parameter only if you want to change the schema.org repository used as source for the SDO Adapter. By standard, SDO Adapter uses a fork of the schema.org repository, which is updated only when schema.org releases a new vocabulary version, and that version passes all tests of SDO Adapter.
Optional defaultFilter?: FilterObject

Sets a default filter for all results provided by the created SDO Adapter. Everytime no filter is passed to a function, this default filter is used.
Optional equateVocabularyProtocols?: boolean

If true, treat namespaces in input vocabularies as equal even if their protocols (http/https) are different. (default = false)
Optional onError?: ErrorFunction

A callback function(msg: string) that is called when an unexpected error happens.
Optional outputFormat?: OutputIRIType
Defines the format in which the IRI results from functions should be returned. This option can be set for the SDO-Adapter on initialization, which becomes the standard (default = "Compact"). After the initialization it is also possible to pass this option to some API-functions to get IRIs in a different format. The options are as follows:
- "Compact": The resulting IRIs are given in compact form, e.g. "schema:Hotel"
- "Absolute": The resulting IRIs are given in absolute form, e.g. "https://schema.org/Hotel"
Optional schemaHttps?: boolean

Enables the use of the https version of the schema.org vocabulary. Only available for schema.org version 9.0 upwards. (default = true)
Optional schemaVersion?: string

The schema.org vocabulary version that should be added to the SDO Adapter right after initialization. You have to pass only the version string, e.g. "13.0". It is also possible to pass "latest" to automatically fetch the latest version of schema.org.
Optional vocabularies?: (Vocabulary | string)[]

Vocabularies that should be added to the SDO Adapter right after initialization. You have to pass the vocabulary either as a JSON-LD object, or as a URL pointing at such a JSON-LD object. If you use the setting schemaVersion then you should not add a schema.org vocabulary here.

ParamObjIRIList

ParamObjIRIList: { filter?: FilterObject; outputFormat?: OutputIRIType }

A parameter object to filter and format the output of a functions that returns a list of IRIs

Type declaration

Optional filter?: FilterObject

The filter to be applied on the result
Optional outputFormat?: OutputIRIType
Defines the format in which the IRI results of this functions should be returned. Use this parameter only if the wished format is different to the default format set for the SDO-Adapter during its initialization. The possible formats are:
- "Compact": The resulting IRIs are given in compact form, e.g. "schema:Hotel"
- "Absolute": The resulting IRIs are given in absolute form, e.g. "https://schema.org/Hotel"

ParamObjIRIListInference

ParamObjIRIListInference: ParamObjIRIList & { implicit?: boolean }

A parameter object to filter and format the output of a functions that returns a list of IRIs. Also includes a reasoning parameter "implicit", which defaults to true and makes it possible to include implicit data in the results based on inferences (e.g. the direct subclasses of a target class are explicit subclasses. The subclasses of those subclasses can be inferred as implicit subclasses for the target class)

example

// the following parameter object uses no filter. It states that the returned result should be formatted as absolute IRIs and that implicit data should be included
const exampleParameters = {
   outputFormat: "Absolute",
   implicit: true
}

SchemaModule

SchemaModule: typeof SchemaModuleLabel[number]

Schema module identifiers which reflect the extension modules of schema.org. More information about the schema modules can be found in Organization of Schemas - Hosted Sections. core is added as an identifier for schema.org terms that belong to no particular extension:

"core" -> core terms of the schema.org vocabulary - belong to no particular extension
"pending" -> The pending section for work-in-progress terms
"health-lifesci" -> The Health and Lifesciences Section
"bib" -> The Bibliographic Section
"auto" -> The Auto Section
"meta" -> The meta section designed to support the implementation of the Schema.org vocabulary itself. They are NOT advocated for widespread use across the web.
"attic" -> The attic section includes terms which are no longer part of the core vocabulary or its extensions. It is encouraged to NOT use these terms.

TermTypeIRIValue

TermTypeIRIValue: typeof TermTypeIRI[TermType]

An IRI (string) indicating the type of Term:

Class -> "rdfs:Class"
Property -> "rdf:Property"
Enumeration -> "schema:Enumeration"
EnumerationMember -> "soa:EnumerationMember"
DataType -> "schema:DataType"

TermTypeLabelValue

TermTypeLabelValue: typeof TermTypeLabel[TermType]

A label (string) indicating the type of Term:

Class -> "Class"
Property -> "Property"
Enumeration -> "Enumeration"
EnumerationMember -> "EnumerationMember"
DataType -> "DataType"

Vocabulary

Vocabulary: { @context: Context; @graph: VocabularyNode[]; @id?: string }

Type declaration

@context: Context
@graph: VocabularyNode[]
Optional @id?: string

Functions

checkFilterValidity

checkFilterValidity(filter?: FilterObject): void

Parameters
- Optional filter: FilterObject
Returns void

checkVocabNodeType

checkVocabNodeType(types: unknown): TermTypeLabelValue

Parameters
- types: unknown
Returns TermTypeLabelValue

constructURLSchemaVocabulary

constructURLSchemaVocabulary(version?: string, schemaHttps?: boolean, commit?: string): Promise<string>

Creates a URL pointing to the Schema.org vocabulary for the wished version. This URL can then be added to the SDOAdapter to retrieve the Schema.org vocabulary. The Schema.org version listing at https://raw.githubusercontent.com/schemaorg/schemaorg/main/versions.json is used for this function. Check https://schema.org/docs/developers.html for more information. The internal cache is used for this function. If you want to reset the cache, use the function .fetchSchemaVersions().
example
```
const { SOA } = require("schema-org-adapter");
const schemaUrl = await SOA.constructURLSchemaVocabulary("13.0");
// creates following URL pointing to the schema.org vocabulary version 13.0
"https://raw.githubusercontent.com/semantifyit/schemaorg/main/data/releases/13.0/schemaorg-all-https.jsonld"
```
Parameters
- version: string = "latest"
  
  The wished Schema.org vocabulary version for the resulting URL (e.g. "5.0", "3.7", or "latest"). default: "latest"
- schemaHttps: boolean = true
  
  Enables the use of the https version of the schema.org vocabulary. Only available for schema.org version 9.0 upwards. (default = true)
- Optional commit: string
  
  The commit string from https://github.com/schemaorg/schemaorg which is taken as source (if not given, the latest commit of our fork at https://github.com/semantifyit/schemaorg is taken). Use this parameter only if you want to change the schema.org repository used as source for the URL generation. By standard, SDO Adapter uses a fork of the schema.org repository, which is updated only when schema.org releases a new vocabulary version, and that version passes all tests of SDO Adapter.
Returns Promise<string>
The URL to the Schema.org vocabulary

create

create(paramObj?: ParamObjCreateSdoAdapter): Promise<SDOAdapter>

Creates a new SDO Adapter instance. The optional parameter object can help you to pass settings to the SDO Adapter. Have a look to understand the possible settings and default values. The minimal setting you would like to pass is the schema.org vocabulary version you want to use.
example
```
const { SOA } = require("schema-org-adapter");
// create a new SDOAdapter instance with the latest version of schema.org
const mySdoAdapter = await SOA.create({schemaVersion: "latest"});
```
Parameters
- Optional paramObj: ParamObjCreateSdoAdapter
  
  An optional parameter object that describes initialization settings for the newly created SDO Adapter instance.
Returns Promise<SDOAdapter>

fetchSchemaVersions

fetchSchemaVersions(cacheClear?: boolean, commit?: string): Promise<VersionsFile>

Returns the schema.org version file, which is fetched once and then saved in local cache. Also sends head-requests to determine if the 'latest' schema.org version is really 'fetch-able'. If not, this head-requests are done again for older versions until the latest valid version is determined and saved in the cache. It is possible to reset the cache with the parameter cacheClear.
example
```
const { SOA } = require("schema-org-adapter");

// version file needed for the first time -> the file is fetched and then saved in cache
let schemaVersions = await SOA.fetchSchemaVersions();

// version file already in cache -> no fetching needed
schemaVersions = await SOA.fetchSchemaVersions();

// passing cacheClear = true -> the file is fetched and then saved in cache again
schemaVersions = await SOA.fetchSchemaVersions(true);
```
Parameters
- cacheClear: boolean = false
  
  If true, delete the local cache of the version file and retrieve it again. (default = false)
- Optional commit: string
  
  The commit string from https://github.com/schemaorg/schemaorg which is taken as source (if not given, the latest commit of our fork at https://github.com/semantifyit/schemaorg is taken). Use this parameter only if you want to change the schema.org repository used as source for the schema versions file. By standard, SDO Adapter uses a fork of the schema.org repository, which is updated only when schema.org releases a new vocabulary version, and that version passes all tests of SDO Adapter.
Returns Promise<VersionsFile>
The version file as JSON object

getLatestSchemaVersion

getLatestSchemaVersion(commit?: string): Promise<string>

Returns the latest version identifier for the schema.org vocabulary. The internal cache is used for this function. If you want to reset the cache, use the function .fetchSchemaVersions().
example
```
const { SOA } = require("schema-org-adapter");
const latestSchemaVersion = await SOA.getLatestSchemaVersion();
// get the latest schema.org vocabulary version identifier
"13.0"
```
Parameters
- Optional commit: string
  
  The commit string from https://github.com/schemaorg/schemaorg which is taken as source (if not given, the latest commit of our fork at https://github.com/semantifyit/schemaorg is taken). Use this parameter only if you want to change the schema.org repository used as source for the schema versions file. By standard, SDO Adapter uses a fork of the schema.org repository, which is updated only when schema.org releases a new vocabulary version, and that version passes all tests of SDO Adapter.
Returns Promise<string>
The latest version of the schema.org vocabulary

getSchemaModuleMatch

getSchemaModuleMatch(termVocabulary: string): SchemaModule | null

Parameters
- termVocabulary: string
Returns SchemaModule | null

isSchemaModule

isSchemaModule(value: string): value is "core" | "health-lifesci" | "pending" | "bib" | "meta" | "auto" | "attic"

Parameters
- value: string
Returns value is "core" | "health-lifesci" | "pending" | "bib" | "meta" | "auto" | "attic"

isTermTypeIRIValue

isTermTypeIRIValue(value: string): value is TermTypeIRIValue

Parameters
- value: string
Returns value is TermTypeIRIValue

isTermTypeLabelValue

isTermTypeLabelValue(value: string): value is TermTypeLabelValue

Parameters
- value: string
Returns value is TermTypeLabelValue

Index

Classes

Type aliases

Functions

Type aliases

Context

FilterObject

Type declaration

Optional fromVocabulary?: string | string[]

Optional fromVocabularyExclude?: string | string[]

Optional isSuperseded?: boolean

Optional schemaModule?: SchemaModule | SchemaModule[]

Optional schemaModuleExclude?: SchemaModule | SchemaModule[]

Optional strictMode?: boolean

Optional termType?: TermTypeLabelValue | TermTypeLabelValue[]

Optional termTypeExclude?: TermTypeLabelValue | TermTypeLabelValue[]

OutputIRIType

ParamObjCreateSdoAdapter

Type declaration

Optional commit?: string

Optional defaultFilter?: FilterObject

Optional equateVocabularyProtocols?: boolean

Optional onError?: ErrorFunction

Optional outputFormat?: OutputIRIType

Optional schemaHttps?: boolean

Optional schemaVersion?: string

Optional vocabularies?: (Vocabulary | string)[]

ParamObjIRIList

Type declaration

Optional filter?: FilterObject

Optional outputFormat?: OutputIRIType

ParamObjIRIListInference

SchemaModule

TermTypeIRIValue

TermTypeLabelValue

Vocabulary

Type declaration

@context: Context

@graph: VocabularyNode[]

Optional @id?: string

Functions

checkFilterValidity

Parameters

Optional filter: FilterObject

Returns void

checkVocabNodeType

Parameters

types: unknown

Returns TermTypeLabelValue

constructURLSchemaVocabulary

Parameters

version: string = "latest"

schemaHttps: boolean = true

Optional commit: string

Returns Promise<string>

create

Parameters

Optional paramObj: ParamObjCreateSdoAdapter

Returns Promise<SDOAdapter>

fetchSchemaVersions

Parameters

cacheClear: boolean = false

Optional commit: string

Returns Promise<VersionsFile>

getLatestSchemaVersion

Parameters

Optional commit: string

Returns Promise<string>

getSchemaModuleMatch

Parameters

termVocabulary: string

Returns SchemaModule | null

isSchemaModule

Parameters

value: string

Returns value is "core" | "health-lifesci" | "pending" | "bib" | "meta" | "auto" | "attic"

isTermTypeIRIValue

Parameters

value: string

Returns value is TermTypeIRIValue