Options
All
  • Public
  • Public/Protected
  • All
Menu

Schema.org Adapter

Index

Classes

Type aliases

Variables

Functions

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

Variables

Const SEMANTIFY_COMMIT

SEMANTIFY_COMMIT: "SEMANTIFY" = "SEMANTIFY"

Const SEMANTIFY_VERSION_FILE_URL

SEMANTIFY_VERSION_FILE_URL: "https://semantify.it/dvs/vocabularies/schema/versions" = "https://semantify.it/dvs/vocabularies/schema/versions"

Functions

checkFilterValidity

checkVocabNodeType

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

  • 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 | VersionsFileSemantify>

  • 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 | VersionsFileSemantify>

    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

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

isTermTypeLabelValue