1.4.2 SPIN Standard Library A collection of generally useful SPARQL functions (expressed as SPIN functions), and SPIN templates. Also provides a top-level classification of functions, and definitions of the standard SPARQL functions. Union template This type can be used for templates that serve as the union (or "collector") of other templates. Union templates differ from other templates in that all spl:Arguments are optional. This means that union templates can be declared as subclasses of multiple other templates, yet when instantiated, only some of the arguments defined by the superclasses need to be filled in. Constraint template Metaclass for CONSTRUCT templates that create spin:ConstraintViolations and can be used as values of spin:constraint. Test case A test to verify that a SPIN function or magic property works as expected, and to generate documentation of example uses of the function. Each TestCase consists of a SPARQL function call or an expression that can be executed with spin:eval, and an expected result. The test framework only needs to execute spin:eval on the expression and compare it with the expected result. The test expression or SELECT query (anything that can be evaluated with spin:eval). The expected result of the test case, or nothing to indicate that an error is expected. true predicate class instance testResult default value test expression optional value type count The end index. true Gets the sub-string of a given string. The index of the first character is 1. substr SUBSTR The start index. The input string. String functions A collection of functions that return strings. true true test Ontology functions A collection of functions performing ontology-related operations. true bnode Constructs a blank node that is distinct from all blank nodes in the dataset being queried and distinct from all blank nodes created by calls to this constructor for other query solutions. If the no argument form is used, every call results in a distinct blank node. If the form with a simple literal is used, every call results in distinct blank nodes for different simple literals, and the same blank node for calls with the same simple literal within expressions for one solution mapping. This functionality is compatible with the treatment of blank nodes in SPARQL CONSTRUCT templates. BNODE A literal input node. true true test Misc functions A collection of functions that are difficult to categorize. true md5 Returns the MD5 checksum, as a hex digit string, calculated on the UTF-8 representation of the simple literal or lexical form of the xsd:string. Hex digits SHOULD be in lower case. MD5 The input literal. Run test cases Runs all spl:TestCases on the current model. testCase expr testCase expected actual expr expected actual expected actual expected testCase expected actual contains Returns an xsd:boolean indicating whether or not the value of ?arg1 contains (at the beginning, at the end, or anywhere within) at least one sequence of collation units that provides a minimal match to the collation units in the value of ?arg2, according to the collation that is used. CONTAINS The sub-string to search for in the input string. The input string. Mathematical functions A collection of functions operating on numbers. true rand Returns a number between 0 (inclusive) and 1.0e0 (exclusive). Different numbers can be produced every time this function is invoked. Numbers should be produced with approximately equal probability. RAND floor Returns the largest (closest to positive infinity) number with no fractional part that is not greater than the value of ?arg1. An error is raised if ?arg1 is not a numeric value. floor The value to get the floor of. Constraint templates Abstract superclass of templates that can be used as spin:constraints. The subclasses are expected to construct spin:ConstraintViolations and use ?this to talk about the instances of the associated class. true Property constraint templates Abstract superclass of constraint templates that constrain exactly one property. The property being constrained. true Property pair constraint templates Abstract base class for templates that take two properties as arguments and establish a relationship between them. The "other" property. true Non-existence property pair constraint The property {?property} must have no values as long as {?otherProperty} has none otherProperty someValue property object message has none otherProperty must have no values because property Property property message ceil Returns the smallest (closest to negative infinity) number with no fractional part that is not less than the value of arg. An error is raised if ?arg1 is not a numeric value. ceil The number to get the ceiling of. Boolean functions A collection of functions that return a boolean value (true or false). true hasValueOfType Checks whether a given subject (?arg1) has at least one value of a given type (?arg3) for a given property (?arg2) or one of its sub-properties. the type to match against the expected property the subject that is expected to have the value p 0 -2 p value value isUntypedLiteral Checks whether a given literal is untyped. This function was introduced because the built-in datatype operand in SPARQL casts untyped literals to xsd:string, making it impossible to check it this way. This function here uses a work-around using sameTerm instead. The literal to test. String length property constraint Represents a constraint that narrows down a property by a minimum and maximum length of the characters of the string representation of its values. This constraint is typically used for string literals, but may also be useful for integers (e.g. 4 digit numbers), and may even be used to limit the length of URIs. Values of {?property} must have between {?minLength} and {?maxLength} characters The minimum number of characters (default to 0). true The maximum number of characters (defaults to unlimited). true property object length object maxLength length maxLength 0 minLength length message characters maxLength and minLength must have between object Value property object message Date functions A collection of functions that operate on date/time literals. true hours Extracts the hours from a date/time literal. hours The dateTime or time argument. add Returns the arithmetic sum of its operands. + the second number the first number The class to get the constraints of. The instance to check. sub property of Checks whether a given property (?arg1) is a (transitive) sub-property of another property (?arg2). The potential super-property. The potential sub-property. 0 -2 Construct default values This template can be attached as spin:constructor to a root class such as rdfs:Resource to ensure that SPIN processors assign default values to certain properties. Looks for any templates attached as spin:constraints to the types of ?this and then assigns their declared spl:defaultValues. Construct default values directType directType 0 -2 type type attribute attribute defaultValue attribute predicate predicate defaultValue true subjectCount Gets the number of values of a given property (?arg1) at a given object (?arg2). The result is the number of matches of (?subject, ?arg1, ?arg2). the object to get the number of subjects of the predicate to get the number of subjects of subject result subject IRI Creates a IRI resource (node) from a given IRI string (?arg1). IRI The IRI string to convert to a resource. divide Returns the arithmetic quotient of its operands. / the second operand the first operand Type property constraint Represents a constraint that narrows down the rdf:type of the values of a property. Values of {?property} must have the type {?type} The class that the values must have as their rdf:type (or a subclass thereof). property object type object message type must have the type object Value property object message Count property constraint templates Abstract superclass of property constraints that compare the number of values with either min or max count. The minimum number of values that the property must have. true The maximum number of values that the property must have. true true Object count property constraint Represents a constraint that can be attached to a class to specify that a given property must have between min and max values. The property {?property} must have between {?minCount} and {?maxCount} values objectCount property maxCount objectCount maxCount minCount objectCount minCount message objectCount Invalid number of values: property message Unique property value constraint Reports an error if the given property has a value that is also used elsewhere, for the same property. Values of {?property} must be unique property value other property value other label already exists elsewhere. value Property must have a unique value, but label property value true test false test URI Equivalent to IRI. URI The IRI string to convert to a resource. struuid Returns a string that is the scheme specific part of UUID. That is, as a simple literal, the result of generating a UUID, converting to a simple literal and removing the initial urn:uuid:. STRUUID le Returns true if ?arg1 <= ?arg2. <= the second operand the first operand seconds Extracts the seconds from a date/time literal. seconds The dateTime or time argument. tz Returns the timezone part of ?arg1 as a simple literal. Returns the empty string if there is no timezone. TZ mul Returns the arithmetic product of its operands. * the second operand the first operand strlang Takes a string (?arg1) and a language (?arg2) and constructs a literal with a corresponding language tag. STRLANG The language tag, e.g. "en-AU". The string value. strends Returns true if the lexical form of ?arg1 ends with the lexical form of ?arg2, otherwise it returns false. STRENDS The sub-string that the input string is supposed to end with. The input string. Regex property constraint Values of {?property} must match the regular expression {?pattern} The regular expression to match. property object pattern object message " pattern must match the regular expression " object Value property message min Takes two arguments and returns the smaller one of them. The second argument. The first argument. result result strdt Constructs a literal with lexical form and type as specified by the arguments. STRDT The datatype of the new literal. The lexical form of the new literal. has argument Checks if a given module class (?module) has at least one declared spl:Argument. The module class to check. class 0 -2 superClass superClass con con the value type of the argument true Provides metadata about an argument of a SPIN Function or Template. Arguments wrap a given rdf:Property (predicate) and specify its value type and whether the argument is optional. When used as spin:constraint, the body of this template will verify that a non-optional value exists and that it has the specified value type. Arguments that have been declared spl:optional true become optional if the type of ?this is spl:UnionTemplate. Argument the default value for the argument true label predicate Missing value for argument false optional optional predicate value template template label ) valueType (expected: predicate Incorrect type of argument valueType predicate value value valueType valueType value predicate label Argument {?predicate} : {?valueType} the property holding the values of each function call a comment describing the argument true indicates whether the argument is optional true UCASE Converts a string to upper case characters. UCASE The input string. round Returns the number with no fractional part that is closest to the argument. If there are two such numbers, then the one that is closest to positive infinity is returned. An error is raised if ?arg1 is not a numeric value. round The number to round. true test minutes Extracts the minutes from a date/time literal. minutes The dateTime or time argument. sha1 Returns the SHA1 checksum, as a hex digit string, calculated on the UTF-8 representation of the simple literal or lexical form of the xsd:string. Hex digits SHOULD be in lower case. SHA1 The input literal. sub Returns the arithmetic difference of its operands. - the second operand the first operand year Extracts the year from a date/time literal. year The date or dateTime argument. primary key URI start Gets the URI start declared as part of a primary key declaration for a given class, using spl:PrimaryKeyPropertyConstraint. The class to get the primary key of. class 0 -2 type type constraint constraint Primary key property constraint Specifies that the given property is a primary key for instances of the associated class (and its subclasses). If a property has been declared to be the primary key then each instance of the class must have exactly one value for that property. Furthermore, the URIs of those instances must start with a given string (arg:uriStart), followed by the URL-encoded primary key value. For example if arg:uriStart is "http://example.org/country-" and the primary key for an instance is "de" then the URI must be "http://example.org/country-de". Finally, as a result of the URI policy, there can not be any other instance with the same value under the same primary key policy. The property {?property} is the primary key and URIs start with {?uriStart} The start of the URIs of well-formed instances of the associated class. rdfs:label cannot be used as primary key label Missing value for primary key property property any label Multiple values of primary key property 1 property property value uri value uriStart uri label uri does not align with the expected URI value Primary key value 1 property label property constraint result result NOT IN Checks whether the value on the left (?arg1) is none of the values on the right (?arg2, ?arg3 ...). NOT IN The value to find. false month Extracts the month from a date/time literal. month The date or dateTime argument. Untyped object property constraint A generic SPIN template that can be used to declare a constraint that all values of a given property must have an rdf:type. Values of {?property} must have a type property object object anyType message must have a type object Value property message isURI Checks whether a node is a URI. isURI the node to check sub class of Checks whether a given class (?arg1) is a (transitive) sub-class of another class (?arg2). The potential super-class. The potential sub-class. 0 -2 strbefore Returns a literal of the same kind (simple literal, plain literal same language tag, xsd:string) as the first argument arg1. The lexical form of the result is the substring of the value of arg1 that precedes in arg1 the first occurrence of the lexical form of arg2; otherwise the lexical form of the result is the empty string. If the lexical form of arg2 is the empty string, the lexical form of the result is the emprty string. STRBEFORE The pattern to find within the input string. The input string. subject in graph Gets the "first" subject of a given predicate (?arg1)/object (?arg2) combination in a given graph (?arg3). Note that if multiple values are present then the result might be unpredictably random. The graph to operate on. The object. The predicate. subject subject Infer default value Can be used to infer default values for a given subject/predicate combination. This is typically assigned as spin:rule to a class. If ?this does not already have a value for a given property {?predicate}, then this will infer the value {?defaultValue}. Default value for {?predicate}: {?defaultValue} The predicate to infer the default value of. The default value to infer. predicate anyValue anyValue predicate defaultValue sha512 Returns the SHA512 checksum, as a hex digit string, calculated on the UTF-8 representation of the simple literal or lexical form of the xsd:string. Hex digits SHOULD be in lower case. SHA512 The input literal. unary plus Returns the operand ?arg1 with the sign unchanged. Semantically, this operation performs no operation. + the operand day Extracts the day from a date/time literal. day The date or dateTime argument. now Gets the current date and time as an xsd:dateTime literal. now Less than other property pair constraint Can be used to define a constraint between two properties (?property and ?otherProperty) enforcing the invariant that the values of ?property must be smaller than the values of ?otherProperty. For example this can be used to state that ex:startDate must be < ex:endDate. Values of {?property} must be less than the values of {?otherProperty} property value otherProperty otherValue otherValue value label otherProperty of otherValue must be less than property of value Value property value label URI functions A collection of functions that create URI resources. true UUID Returns a fresh IRI from the UUID URN scheme. Each call of UUID() returns a different UUID. It must not be the "nil" UUID (all zeroes). The variant and version of the UUID is implementation dependent. UUID Argument value value is numeric Returns true if arg1 is a numeric value. Returns false otherwise. term is numeric if it has an appropriate datatype (see the section Operand Data Types) and has a valid lexical form, making it a valid argument to functions and operators taking numeric arguments. isNumeric The node to check whether it's numeric. strstarts Returns true if the lexical form of ?arg1 begins with the lexical form of ?arg2, otherwise it returns false. STRSTARTS The sub-string that the input string is supposed to begin with. The input string. max Takes two arguments and returns the larger one of them. The second argument. The first argument. result result object sub prop Gets the object of a given subject (?arg1) / predicate (?arg2) combination, also taking the sub-properties of ?arg2 into account. Note that if multiple values are present then the result might be unpredictably random. The predicate to get the object of (including sub-properties of it). The subject to get the object from. property 0 -2 property object object true LCASE Converts a string to lower case characters. LCASE The input string. hasValue Checks whether a given resource (?arg1) has a given value (?arg3) for a given property (?arg2) or one of the sub-properties of it. the expected value the property that is expected to hold the value the subject that is expected to have the value p 0 -2 p timezone Returns the timezone part of ?arg1 as an xsd:dayTimeDuration. Raises an error if there is no timezone. TIMEZONE The input time. relevant property at class A magic property that establishes a relationship between properties (left) and classes (right) to determine which properties are "relevant" for the class. Relevant means that they have the class in their domain and/or restrictions, including superclasses and sub-properties (unless they define their own domain). Domains consisting of an owl:unionOf are also handled. Note that the performance of the body of this magic property has been optimized for the case in which the class is given, so ideally use this for queries such as ?property spl:relevantPropertyAtClass skos:Concept . The property. class 0 -2 superClass property superClass superClass property list 0 -2 listSegment property list listSegment superClass 0 -2 property anyDomain property class class true object in graph Gets the object of a given subject (?arg1) / predicate (?arg2) combination in a given graph ?arg3. Note that if multiple values are present then the result might be unpredictably random. The graph to query in. The predicate to get the object of. The subject to get the object from. object object Existence property pair constraint The property {?property} must have a value whenever {?otherProperty} has a value otherProperty someValue property object message has otherProperty must have a value because property Property property message SPIN Overview Finds all constraints and rules attached to classes in the current graph, using spin:constraint, spin:constructor, spin:rule or their sub-properties. The result set will contain the associated class, the predicate, and the SPIN rule. SPIN Overview bp bp bp property 0 -2 bp class property rule class rule rule the minimum number of values permitted for the property true Defines an "attribute" of a class. Attribute definitions bundle common modeling patterns known from object-oriented languages like UML. Each attribute can have min and max cardinality, a value type and a default value. The attribute links a class with one RDF property. This template should be used as spin:constraints on a class to make sure that classes meet the expected cardinalities and valueType constraints. If a model wants to use spl:defaultValue, then it should instantiate the spl:ConstructDefaultValues as a spin:constructor at some root class, such as rdfs:Resource. the RDF property holding the attribute value the default value of the attribute true the maximum number of values permitted for the property true the type that all values of the property must have true Attribute Attribute {?predicate} : {?valueType} [{?minCount},{?maxCount}] valueType predicate value valueType value maxCount predicate maxCount minCount predicate minCount predicate a comment describing the meaning of this attribute true class property rule sha256 Returns the SHA256 checksum, as a hex digit string, calculated on the UTF-8 representation of the simple literal or lexical form of the xsd:string. Hex digits SHOULD be in lower case. SHA256 The input literal. subject Gets the "first" subject of a given predicate (?arg1)/object (?arg2) combination. Note that if multiple values are present then the result might be unpredictably random. The object. The predicate. subject subject unary minus Returns the operand ?arg1 with the sign reversed. If ?arg1 is positive, its negative is returned; if it is negative, its positive is returned. - the operand abs Returns the absolute value of arg. An error is raised if arg is not a numeric value. abs The input value. false IN Checks whether the value on the left (?arg1) is one of the values on the right (?arg2, ?arg3 ...). IN The value to find. All arguments Gets a list of all spl:Arguments declared at a given class and its superclasses. All spl:Arguments of {?class} The class to get the arguments of. class 0 -2 atClass atClass arg arg arg atClass The pattern to replace. The replacement string. Replaces each non-overlapping occurrence of a regular expression pattern with a replacement string. Regular expession matching may involve modifier flags. The input string. replace REPLACE Additional flags for the replacement. true lang Returns the language tag of ?arg1, if it has one. It returns "" if the literal has no language tag. Node that the RDF data model does not include literals with an empty language tag. lang the literal to get the language of langMatches Returns true if language-tag (first argument) matches language-range (second argument) per the basic filtering scheme defined in [RFC4647] section 3.3.1. langMatches the language tag that ?arg1 must have the literal that is expected to have ?arg2 as language tag sha384 Returns the SHA384 checksum, as a hex digit string, calculated on the UTF-8 representation of the simple literal or lexical form of the xsd:string. Hex digits SHOULD be in lower case. SHA384 The input literal. has primary key Checks if a given class has a declared primary key, using spl:PrimaryKeyPropertyConstraint. The class to get the primary key of. primaryKey class primaryKey strafter Returns a literal of the same kind (simple literal, plain literal same language tag, xsd:string) as the first argument arg1. The lexical form of the result is the substring of the value of arg1 that proceeds in arg1 the first occurrence of the lexical form of arg2; otherwise the lexical form of the result is the empty string. If the lexical form of arg2 is the empty string, the lexical form of the result is the emprty string. STRAFTER The pattern to find within the input string. The input string. is primary key property of instance Checks if a given property is the primary key of a given instance. The property that may or may not be the primary key. The instance to check. instance type pk type pk property Range property constraint Represents a constraint that narrows down a property by a minimum and maximum value compared by <= and >=. Values of {?property} must be within the interval [ {?min} , {?max} ] The minimum value. true The maximum value. true property object max object max min object min message ] max , min must be in the interval [ object Value property object message encode_for_uri ENCODE_FOR_URI The string to convert. EXISTS The filter function EXISTS. The graph pattern is stored in sp:elements. EXISTS constraint class class 0 -2 the second operand the first operand datatype datatype datatype datatype object the match pattern object isIRI Checks whether a given node is a IRI node. isIRI the node being tested property constraint type constraint the second operand bound Returns true if ?arg1 is bound to a value. Returns false otherwise. Variables with the value NaN or INF are considered bound. bound the variable or expression that is checked the instance being tested Note that in TopBraid this function has been implemented in native Java code, for performance reasons. Checks whether a given resource (?arg1) has a given type (?arg2). In order to fulfill this condition, there must either be a triple ?arg1 rdf:type ?arg2, or ?instance rdf:type ?subClass where ?subClass is a subclass of ?arg2. If the first argument is a literal, then the second argument must be the matching XSD datatype. the type that the instance must have {?arg1} instance of {?arg2} instanceOf the node being checked object strlen Computes the length of a given input string. STRLEN The input string. the property to get the number of values of result The function result if ?arg1 is true. the literal to get the datatype of the second operand the input string the first operand the subject to get the number of objects of the operand to negate isLiteral Checks whether a given node is a literal. isLiteral the node being tested property the second value to compare and Return the logical AND between two (boolean) operands. && the second operand of the intersection the first operand of the intersection object type The subject to get the object from. Note that in TopBraid this function has been implemented in native Java code, for performance reasons. object Gets the object of a given subject (?arg1) / predicate (?arg2) combination. Note that if multiple values are present then the result might be unpredictably random. Furthermore, if one of the arguments is unbound, it will return the first match of the resulting SPO pattern. These scenarios are strongly discouraged but remain left supported for backward compatibility reasons. The predicate to get the object of. the first operand primary key property Gets the primary key property declared for a given class, using spl:PrimaryKeyPropertyConstraint. The class to get the primary key of. class 0 -2 The function result if ?arg1 is false. concat The CONCAT built-in function. Creates a single string by concatenating all arguments from left to right. Note that if any one of the arguments is unbound (null) then the whole result string will be unbound. CONCAT The expression to evaluate. Should be a sp:Select, sp:Ask, a sp:Variable or an instance of a SPARQL function class, but may also be a simple RDF value. lt Returns true if ?arg1 < ?arg2. < the second operand datatype Returns the datatype IRI of argument ?arg1; returns xsd:string if the parameter is a simple literal. datatype Returns true if a string (?arg1) matches the regular expression supplied as a pattern (?arg2) as influenced by the value of flags (?arg3), otherwise returns false. the flags true regex regex the node to convert to string same term Returns TRUE if ?arg1 and ?arg2 are the same RDF term as defined in Resource Description Framework (RDF): Concepts and Abstract Syntax; returns FALSE otherwise. sameTerm the second argument the first argument objectCount Gets the number of values of a given property (?arg2) at a given subject (?arg1). The result is the number of matches of (?arg1, ?arg2, ?object). COALESCE Takes any number of arguments, and returns the first bound argument, starting at the left. COALESCE the first operand eq Returns true if both arguments are equal. = the first value to compare not Returns the boolean negation of the argument. ! gt Returns true if ?arg1 > arg2. > A condition to evaluate - if true then the ?arg2 will be returned, otherwise ?arg3. str Returns the lexical form of ?arg1 (a literal); returns the codepoint representation of ?arg1 (an IRI). This is useful for examining parts of an IRI, for instance, the host-name. str isBlank Checks whether a given node is a blank node. isBlank ne Returns true if ?arg1 != ?arg2. != the first operand IF The SPARQL 1.1 built-in function IF. IF or Returns the logical OR between two (boolean) operands. || ge Returns true if ?arg1 >= ?arg2. >= the second operand NOT EXISTS The filter function NOT EXISTS. The graph pattern is stored in sp:elements. NOT EXISTS