DsUtilitiesV7 | DS-Utilities

DsUtilitiesV7 is a Class that offers an API for DS-Specification 7.0

Instances of this class can be created with following static functions of this library:

Below you can find the API functions provided by this class (categorized by functionality).

example

// following DsUtilitiesV7 instance is used in the code examples below
const myDsUtilitiesV7 = DsUtil.getDsUtilitiesForDsSpecVersion("7.0");

Hierarchy

DsUtilitiesBase
- DsUtilitiesV7

General

extractSdoVersionNumber

extractSdoVersionNumber: (schemaVersionValue: string) => string = extractSdoVersionNumber

Type declaration

- (schemaVersionValue: string): string
- Extracts the schema.org version number (as string) from the given schema.org version URL.
  This function accepts URLs with following formats (any protocol variant is allowed - http/https):
  - "https://schema.org/docs/releases.html#v10.0" -> "10.0"
  - "https://schema.org/version/3.4/" -> "3.4"
  example
  myDsUtilities.extractSdoVersionNumber("https://schema.org/version/12.0/"); // "12.0"
  Parameters
  - schemaVersionValue: string
    
    a URL specifying a schema.org version
  Returns string
  The version number as a string

getDsSpecificationVersion

getDsSpecificationVersion: (ds: DsGeneric) => string = getDsSpecificationVersion

Type declaration

- (ds: DsGeneric): string
- Identifies the used DS-Specification version used by the given Domain Specification.
  example
  const usedVersion = myDsUtilities.getDsSpecificationVersion(exampleDs); // "7.0" (assuming the given DS 'exampleDs' uses DsV7)
  Parameters
  - ds: DsGeneric
    
    The input Domain Specification
  Returns string
  The detected DS-Specification version

getDsUtilitiesVersion

getDsUtilitiesVersion: () => "7.0" = getDsUtilitiesVersion

Type declaration

- (): "7.0"
- Returns the used DS-Specification version of this DS-Utilities instance, which is "7.0".
  
  DS-Utilities instances are always bound to a specific DS-Specification version.
  example
  const dsSpecificationVersion = myDsUtilitiesV7.getDsUtilitiesVersion(); // "7.0"
  Returns "7.0"

UI-Interaction

getDataTypeLabel

getDataTypeLabel: (dsDataType: DataTypeDsV7) => string = getDataTypeLabel

Type declaration

- (dsDataType: DataTypeDsV7): string
- Returns a human-readable label for the given DS-DataType.
  
  DS-DataTypes are listed in the DS-V7 Specification in the XSD column.
  example
  const labelBool = myDsUtilitiesV7.getDataTypeLabel("xsd:boolean"); // "Boolean" const labelLangString = myDsUtilitiesV7.getDataTypeLabel("rdf:langString"); // "Localized Text"
  Parameters
  - dsDataType: DataTypeDsV7
    
    a compacted IRI representing a DataType of DS-V7 (from XSD or RDF, e.g. "xsd:string" or "rdf:langString")
  Returns string
  a human-readable label for the given DataType

getDsAuthorName

getDsAuthorName: (ds: DsV7) => string | undefined = getDsAuthorName

Type declaration

- (ds: DsV7): string | undefined
- Returns the author name of the given DS.
  
  schema:author is optional in DS-V7.
  example
  const name = myDsUtilitiesV7.getDsAuthorName(exampleDs); // "John Doe"
  Parameters
  - ds: DsV7
    
    the input Domain Specification
  Returns string | undefined
  The author name of the given DS, if any

getDsDescription

getDsDescription: (ds: DsV7, language?: string) => string | undefined = getDsDescription

Type declaration

- (ds: DsV7, language?: string): string | undefined
- Returns the description of the given DS for a language (there could be descriptions in different languages).
  
  schema:description is optional in DS-V7.
  example
  const description = myDsUtilitiesV7.getDsDescription(exampleDs); // "This is an example Domain Specification." const descriptionSpanish = myDsUtilitiesV7.getDsDescription(exampleDs, "es"); // "Esta es una DS ejemplar."
  Parameters
  - ds: DsV7
    
    the input Domain Specification
  - Optional language: string
    
    the wished language for the description
  Returns string | undefined
  The description of the given DS, if any

getDsExternalVocabularies

getDsExternalVocabularies: (ds: DsV7) => string[] = getDsExternalVocabularies

Type declaration

- (ds: DsV7): string[]
- Returns the used external vocabularies of the given DS.
  
  ds:usedVocabulary is optional in DS-V7.
  example
  const name = myDsUtilitiesV7.getDsExternalVocabularies(exampleDs); // [ "https://semantify.it/voc/IaiA2RES_" ]
  Parameters
  - ds: DsV7
    
    the input Domain Specification
  Returns string[]
  Array with the used external vocabularies (empty if none)

getDsName

getDsName: (ds: DsV7, language?: string) => string | undefined = getDsName

Type declaration

- (ds: DsV7, language?: string): string | undefined
- Returns the name of the given DS for a language (there could be names in different languages).
  
  schema:name is optional in DS-V7.
  example
  const name = myDsUtilitiesV7.getDsName(exampleDs); // "Example DS" const nameSpanish = myDsUtilitiesV7.getDsName(exampleDs, "es"); // "DS ejemplar"
  Parameters
  - ds: DsV7
    
    the input Domain Specification
  - Optional language: string
    
    the wished language for the name
  Returns string | undefined
  The name of the given DS, if any

getDsSchemaVersion

getDsSchemaVersion: (ds: DsV7) => string = getDsSchemaVersion

Type declaration

- (ds: DsV7): string
- Returns the used schema.org version of the given DS.
  
  schema:schemaVersion is mandatory in DS-V7.
  example
  const sdoVersion = myDsUtilitiesV7.getDsSchemaVersion(exampleDs); // "11.0"
  Parameters
  - ds: DsV7
    
    the input Domain Specification
  Returns string
  The schema.org version identifier as string, e.g. "11.0"

getDsTargetClasses

getDsTargetClasses: (ds: DsV7) => string[] = getDsTargetClasses

Type declaration

- (ds: DsV7): string[]
- Returns the target classes of the given DS.
  
  sh:targetClass is optional in DS-V7.
  example
  const targetClasses = myDsUtilitiesV7.getDsTargetClasses(exampleDs); // [ "schema:Hotel", "schema:Restaurant" ]
  Parameters
  - ds: DsV7
    
    the input Domain Specification
  Returns string[]
  Array with the target classes (empty if none)

getDsVersion

getDsVersion: (ds: DsV7) => string | undefined = getDsVersion

Type declaration

- (ds: DsV7): string | undefined
- Returns the version of the given DS (the version of the DS instance itself).
  
  schema:version is optional in DS-V7.
  example
  const version = myDsUtilitiesV7.getDsVersion(exampleDs); // "1.00"
  Parameters
  - ds: DsV7
    
    the input Domain Specification
  Returns string | undefined
  The ds version as string, e.g. "1.04"

prettyPrintCompactedIRIs

prettyPrintCompactedIRIs: (compactedIRIs: string | string[]) => string = prettyPrintCompactedIRIs

Type declaration

- (compactedIRIs: string | string[]): string
- Returns the "pretty" version of a compacted IRI (single IRI or array of IRIs). If an IRI belongs to schema.org, then the IRI is returned without the schema: vocabulary indicator.
  example
  const targetClasses = [ "schema:Hotel", "ex:SkiLift" ]; const prettifiedTargetClasses = myDsUtilities.prettyPrintCompactedIRIs(targetClasses); // "Hotel + ex:SkiLift" const property = "schema:description"; const prettifiedProperty = myDsUtilities.prettyPrintCompactedIRIs(property); // "description"
  Parameters
  - compactedIRIs: string | string[]
    
    the input IRI or array of IRIs
  Returns string
  The pretty-string for the given input

DS-Structure

generateInnerNodeId

generateInnerNodeId: (ds?: DsV7) => string = generateInnerNodeId

Type declaration

- (ds?: DsV7): string
- Creates a new fragment-id according to the DS-V7 specification.
  
  It is possible to pass a Domain Specification as parameter to ensured that the generated fragment-id has not been used in the given DS yet.
  example
  const newFragmentId = myDsUtilitiesV7.generateInnerNodeId(exampleDs); // "AfgGa"
  Parameters
  - Optional ds: DsV7
    
    the input Domain Specification
  Returns string
  A new the fragment-id

getDsDataTypeForSchemaDataType

getDsDataTypeForSchemaDataType: (schemaDataType: DataTypeSchemaV7) => DataTypeDsV7 = getDsDataTypeForSchemaDataType

Type declaration

- (schemaDataType: DataTypeSchemaV7): DataTypeDsV7
- Returns the corresponding DS-V7 datatype (XSD/RDF) for a given schema.org datatype, according to the DsV7-DataType-Mapping.
  
  ATTENTION: for schema:Text the value xsd:string is always returned (no rdf:langString or rdf:HTML)
  example
  const dsDataType = myDsUtilitiesV7.getDsDataTypeForSchemaDataType("schema:URL"); // "xsd:anyURI"
  Parameters
  - schemaDataType: DataTypeSchemaV7
    
    a compacted IRI representing a DataType of schema.org (e.g. schema:Text)
  Returns DataTypeDsV7
  the corresponding DS-V7 Datatype (from XSD or RDF)

getDsId

getDsId: (ds: DsV7) => string = getDsId

Type declaration

- (ds: DsV7): string
- Returns the @id of the given DS (for DS-V7 this @id is found in the root node).
  
  An @id is mandatory in DS-V7.
  example
  const dsId = myDsUtilitiesV7.getDsId(exampleDs); // "https://semantify.it/ds/_1hRVOT8Q"
  Parameters
  - ds: DsV7
    
    the input Domain Specification
  Returns string
  The @id of the given Domain Specification

getDsRootNode

getDsRootNode: (ds: DsV7) => RootNodeV7 = getDsRootNode

Type declaration

- (ds: DsV7): RootNodeV7
- Returns a reference to the root node of the given Domain Specification.
  example
  const rootNode = myDsUtilitiesV7.getDsRootNode(exampleDs); // returns a JS object reference to the root node
  Parameters
  - ds: DsV7
    
    The input Domain Specification
  Returns RootNodeV7
  The root node of the given Domain Specification

getDsStandardContext

getDsStandardContext: () => ContextV7 = getDsStandardContext

Type declaration

(): ContextV7

Returns the standard @context for DS-V7.

example

const standardContext = myDsUtilitiesV7.getDsStandardContext();
// returns the DS-V7 standard @context as JS object

Returns ContextV7

The standard @context for DS-V7

getSchemaDataTypeForDsDataType

getSchemaDataTypeForDsDataType: (dsDataType: DataTypeDsV7) => DataTypeSchemaV7 = getSchemaDataTypeForDsDataType

Type declaration

- (dsDataType: DataTypeDsV7): DataTypeSchemaV7
- Returns the corresponding schema.org datatype (XSD/RDF) for a given DS-V7 datatype, according to the DsV7-DataType-Mapping.
  example
  const schemaDataType = myDsUtilitiesV7.getSchemaDataTypeForDsDataType("xsd:anyURI"); // "schema:URL"
  Parameters
  - dsDataType: DataTypeDsV7
    
    a compacted IRI representing a DataType of DS-V7 (from XSD or RDF, e.g. xsd:string or rdf:langString)
  Returns DataTypeSchemaV7
  The corresponding schema.org Datatype, e.g. schema:URL

identifyDsGrammarNodeType

identifyDsGrammarNodeType: (dsNode: DsNodeGeneric, ds: DsV7, followReference: boolean, sdoAdapter?: SDOAdapter) => DsGrammarNodeTypeV7 = identifyDsGrammarNodeType

Type declaration

- (dsNode: DsNodeGeneric, ds: DsV7, followReference: boolean, sdoAdapter?: SDOAdapter): DsGrammarNodeTypeV7
- Returns the grammar-type of the given DS-Node within the given Populated Domain Specification.
  
  It is possible to pass an SDO-Adapter to tell a standard enumeration apart from a standard class. If no SDO-Adapter is given, a standard class is assumed.
  
  If a reference node is passed and the parameter followReference is set to true, then the grammar type of the referenced node is returned (e.g. internal reference that points to a Restricted Class -> RestrictedClass) instead of the type of the reference node itself.
  
  The possible DS-Grammar Node types are listed in the documentation of PathTokenObjectV7.
  example
  const nodeDsGrammarType = myDsUtilitiesV7.identifyDsGrammarNodeType(exampleNode, exampleDs, true); // "RestrictedClass" - assume 'exampleNode' is a Restricted Class Node
  Parameters
  - dsNode: DsNodeGeneric
    
    the input DS Node
  - ds: DsV7
    
    the input DS (populated)
  - followReference: boolean
    
    if true, the type of the referenced node is returned, instead of the type of the reference
  - Optional sdoAdapter: SDOAdapter
    
    A SDO-Adapter instance (already initialized with the wished vocabularies)
  Returns DsGrammarNodeTypeV7
  the type of the given node

reorderDs

reorderDs: (ds: DsV7) => void = reorderDs

Type declaration

- (ds: DsV7): void
- Reorders the attributes of all nodes of the given Domain Specification according to their order in the Key-Value tables in the DsV7-Specification.
  example
  myDsUtilitiesV7.reorderDs(exampleDs);
  Parameters
  - ds: DsV7
    
    the input Domain Specification
  Returns void

reorderDsNode

reorderDsNode: (dsNode: DsNodeGeneric) => void = reorderDsNode

Type declaration

- (dsNode: DsNodeGeneric): void
- Reorders the attributes of the given DS-Node according to their order in the Key-Value table in the DsV7-Specification.
  
  The corresponding node type is detected automatically. Works only for certain ds grammar node types.
  example
  myDsUtilitiesV7.reorderDsNode(exampleDsNode);
  Parameters
  - dsNode: DsNodeGeneric
    
    the input node from a Domain Specification
  Returns void

DS-Path

dsPathAddition

dsPathAddition: (dsPath: string, additionType: PathGrammarNodeTypeV7, inputForPath?: string | string[]) => string = dsPathAddition

Type declaration

- (dsPath: string, additionType: PathGrammarNodeTypeV7, inputForPath?: string | string[]): string
- Appends a new token to a given DS-Path.
  A DS-Path can be initialized with the function dsPathInit().
  
  The inputForPath-parameter and the resulting addition to the DS-Path depend on the token type (parameter additionType) to be added:
  - additionType = Property -> inputForPath must be the IRI of the Property, e.g. schema:url
  - additionType = DataType -> inputForPath must be the IRI of the DataType, e.g. xsd:string
  - additionType = Class or Enumeration -> inputForPath must be the IRIs of classes/enumeration as array, e.g. [ "schema:Room", "schema:Product" ] or [ "schema:DayOfWeek" ]
  - additionType = RootReference -> inputForPath is not needed
  - additionType = InternalReference -> inputForPath must be the @id of the internal node, e.g. https://semantify.it/ds/_1hRVOT8Q#sXZwe
  - additionType = ExternalReference -> inputForPath must be the @id of the external node, e.g. https://semantify.it/ds/_1hRVOT8Q
  - additionType = InternalExternalReference -> inputForPath must be the @id of the internal node from an external node, e.g. https://semantify.it/ds/_1hRVOT8Q#sXZwe
  example
  const oldPath = "$.schema:address"; const newPath = myDsUtilitiesV7.dsPathAddition(oldPath, "Class", [ "schema:PostalAddress" ] ); // "$.schema:address/schema:PostalAddress"
  Parameters
  - dsPath: string
    
    the given DS-Path to augment
  - additionType: PathGrammarNodeTypeV7
    
    the kind of addition to be added
  - Optional inputForPath: string | string[]
    
    input that depends on the given additionType, which is used for the dsPath addition
  Returns string
  the resulting DS-Path

dsPathGetNode

dsPathGetNode: (ds: DsV7, dsPath: string, resolveReference?: boolean) => DsNodeV7 = dsPathGetNode

Type declaration

- (ds: DsV7, dsPath: string, resolveReference?: boolean): DsNodeV7
- Returns the corresponding node within the given Domain Specification based on the given DS-Path. (As reference, not as deep copy)
  
  The parameter resolveReference (default = false) allows to set the behaviour with reference nodes: If true, and the last token of the path is a reference node, then the referenced objected will be returned. Else the reference object will be returned.
  example
  const targetNode = myDsUtilitiesV7.dsPathGetNode(exampleDs, "$.schema:address/schema:PostalAddress"); // the resolved target node is a class node for "schema:PostalAddress" within the Domain Specification "exampleDs"
  Parameters
  - ds: DsV7
    
    The input Domain Specification
  - dsPath: string
    
    The input DS-Path
  - resolveReference: boolean = false
    
    If true, and the last token of the path is a reference node, then the referenced objected will be returned. Else the referencing object will be returned.
  Returns DsNodeV7
  The node at the given DS-Path (by reference)

dsPathIdentifyNodeType

dsPathIdentifyNodeType: (dsNode: DsNodeGeneric, ds: DsV7) => PathGrammarNodeTypeV7 = dsPathIdentifyNodeType

Type declaration

- (dsNode: DsNodeGeneric, ds: DsV7): PathGrammarNodeTypeV7
- Returns the DS-Path-type of the given DS-Node within the given Domain Specification. The syntax and @id of the given node are analyzed to determine its DS-Path-type.
  
  The different DS-Path-types (a.k.a. DS-Path-token-type) are listed in the documentation of PathTokenObjectV7.
  example
  const nodeType = myDsUtilitiesV7.dsPathIdentifyNodeType(exampleDsNode, exampleDs); // "InternalReference" (assuming the given exampleDsNode is such an internal reference)
  Parameters
  - dsNode: DsNodeGeneric
    
    the input DS-Node
  - ds: DsV7
    
    the input Domain Specification
  Returns PathGrammarNodeTypeV7
  the DS-Path-type of the given node

dsPathInit

dsPathInit: (nodeType?: PathGrammarNodeTypeV7, nodeId?: string) => string = dsPathInit

Type declaration

- (nodeType?: PathGrammarNodeTypeV7, nodeId?: string): string
- Initializes a DS-Path, based on the given input parameter.
  Keep in mind that paths can only start with a @graph-node (a DS-Node that resides directly in the @graph array of the Domain Specification), the only exception is the @context path. Details about the different reference types can be found in the DS-V7 Documentation.
  
  The parameter nodeType (default = "RootNode") must be one of the following:
  - "RootNode": The DS-Path starts at the root node of the Domain Specification, this is the standard.
  - "InternalReferenceDefinition": The DS-Path starts with an internal reference definition.
  - "ExternalReferenceDefinition": The DS-Path starts with an external reference definition.
  - "InternalExternalReferenceDefinition": The DS-Path starts with an internal reference definition of an external reference.
  - "Context": The DS-Path points to the @context of the Domain Specification.
  The parameter nodeId must be used if the DS-Path starts with a reference definition, and the value for this parameter is the @id of that reference definition, e.g. "https://semantify.it/ds/_1hRVOT8Q".
  
  The newly created DS-Path can be augmented with the function dsPathAddition().
  example
  const newDsPath1 = myDsUtilitiesV7.dsPathInit(); // nodeType defaults to "RootNode" // "$" const newDsPath2 = myDsUtilitiesV7.dsPathInit("InternalExternalReferenceDefinition", "https://semantify.it/ds/_1hRVOT8Q#lwioY"); // "_1hRVOT8Q#lwioY"
  Parameters
  - nodeType: PathGrammarNodeTypeV7 = PGN.root
    
    the node type of the initial token, defaults to "RootNode"
  - Optional nodeId: string
    
    the id of the node which starts the DS-path. Can be left blank in case of "RootNode" or "Context"
  Returns string
  the generated DS-Path

tokenizeDsPath

tokenizeDsPath: (ds: DsV7, dsPath: string) => PathTokenObjectV7[] = tokenizeDsPath

Type declaration

- (ds: DsV7, dsPath: string): PathTokenObjectV7[]
- Returns an array of objects, representing the tokens of a given DS-Path.
  
  There is a dedicated documentation for such a DS-Path-Token-Object.
  example
  const dsPathTokens = myDsUtilitiesV7.tokenizeDsPath(exampleDs, "$.schema:creditText/xsd:string"); // creates an array with 3 DS-Path-Token-Objects, each one representing a token of the given DS-Path
  Parameters
  - ds: DsV7
    
    The input Domain Specification
  - dsPath: string
    
    The input DS-Path
  Returns PathTokenObjectV7[]
  an Array of path-tokens based on the given input

Verification

checkClassMatch

checkClassMatch: (targetClasses: string[], classesToCheck: string[], sdoAdapter: SDOAdapter) => boolean = checkClassMatch

Type declaration

- (targetClasses: string[], classesToCheck: string[], sdoAdapter: SDOAdapter): boolean
- Returns true if the given classes are a valid match for the given targetClasses following the DS-V7 semantics.
  
  This matching is important for the Class-SubClass relationship (e.g. subDS, or range subclass)
  
  This function needs the SDO-Adapter library to work. The given sdoAdapter must be already initialized with the wished vocabularies.
  example
  const isMatch = myDsUtilitiesV7.checkClassMatch( [ "schema:LodgingBusiness" ], [ "schema:Hotel" ], sdoAdapterInstance ); // "true" - (Hotel is a subclass of LodgingBusiness)
  Parameters
  - targetClasses: string[]
    
    The target classes (DS)
  - classesToCheck: string[]
    
    The classes to be checked (Data)
  - sdoAdapter: SDOAdapter
    
    A SDO-Adapter instance
  Returns boolean
  true if the given classes to check are valid for the given target classes

verifyDs

verifyDs: (ds: DsV7, config?: VerificationConfigV7) => VerificationReportV7 = verifyDs

Type declaration

- (ds: DsV7, config?: VerificationConfigV7): VerificationReportV7
- Verifies if the given Domain Specification complies to the DS-V7 specification.
  
  It is possible to pass a config object to this verification, where the expected grammar of the DS can be configured. This function returns a meta verification report.
  example
  const verificationReport = myDsUtilitiesV7.verifyDs(exampleDs); // returns a verification report for the exampleDs
  Parameters
  - ds: DsV7
    
    the input Domain Specification
  - config: VerificationConfigV7 = {}
    
    config object with options for the meta verification
  Returns VerificationReportV7
  verification report

Hierarchy

Index

General

UI-Interaction

DS-Structure

DS-Path

Verification

General

extractSdoVersionNumber

Type declaration

Parameters

schemaVersionValue: string

Returns string

getDsSpecificationVersion

Type declaration

Parameters

ds: DsGeneric

Returns string

getDsUtilitiesVersion

Type declaration

Returns "7.0"

UI-Interaction

getDataTypeLabel

Type declaration

Parameters

dsDataType: DataTypeDsV7

Returns string

getDsAuthorName

Type declaration

Parameters

ds: DsV7

Returns string | undefined

getDsDescription

Type declaration

Parameters

ds: DsV7

Optional language: string

Returns string | undefined

getDsExternalVocabularies

Type declaration

Parameters

ds: DsV7

Returns string[]

getDsName

Type declaration

Parameters

ds: DsV7

Optional language: string

Returns string | undefined

getDsSchemaVersion

Type declaration

Parameters

ds: DsV7

Returns string

getDsTargetClasses

Type declaration

Parameters

ds: DsV7

Returns string[]

getDsVersion

Type declaration

Parameters

ds: DsV7

Returns string | undefined

prettyPrintCompactedIRIs

Type declaration

Parameters

compactedIRIs: string | string[]

Returns string

DS-Structure

generateInnerNodeId

Type declaration

Parameters

Optional ds: DsV7

Returns string

getDsDataTypeForSchemaDataType

Type declaration

Parameters

schemaDataType: DataTypeSchemaV7

Returns DataTypeDsV7