Core Vocabulary defines the OSLC Core RDF vocabulary terms and resources, that have broad applicability across various domains.

Introduction

Various resources and properties may be so commonly used or apply so broadly that it makes sense to define them in one place so they can be easily reused. Some common examples are short names or labels, error messages, discussion threads, traceability/impacts relationship behavior or annotating other vocabulary terms.

Terminology

Terminology uses and extends the terminology and capabilities of OSLC Core Overview [[!OSLCCore3]], W3C Linked Data Platform [[!LDP]], W3C's Architecture of the World Wide Web [[WEBARCH]], Hyper-text Transfer Protocol [[!HTTP11]].

Archived Resource
A resource in which an explicit action has been performed to mark the resource as no longer active and may be removed from typical user interactions. As a consequence, an archived resource should be considered immutable.

References

Motivation

Most OSLC vocabularies and resource shape constraints on usages of those vocabularies are given in the various OSLC domain specifications. The motivation for these domain specifications is to define agreed upon, formalized vocabulary terms for key elements in the domain. Domain vocabularies are not intended to restrict what vocabularies servers actually use for those domains, or what domains they support. Rather vocabularies establish a common core of domain terms that reduce accidental variability and foster greater interchange and interoperability between tools that support and users that make use of domains. Servers are free to extend the domains and integrate across domains as required to realize their provided capabilities.

OSLC Core takes a similar approach for common terms that are used across most domains. The intent is to provide a foundation for building domains that again reduces unnecessary variability, and eliminates the need for the various domain specifications to redundantly define similar terms. The follow paragraphs describe the kinds of common terms defined by OSLC core in order to achieve the stated intent.

Archived Resources are typically found in large systems in which an immutable copy of the state of a resource at a given time is captured. The purpose may vary in that it could be simply a way to facilitate access to a backup or snapshot of a resource at a particular point in time. Another use may be to indicate that a resource has been deleted, but is saved by the system for historical or legal reasons. Having a consistent way to indicate that a resource, or a set of them, has been archived helps when defining certain views of the resources or queries. Archived Resources may be identified by having a property oslc:archived, with value true.

Many different kinds of applications have a way to provide comments or notes related to a given resource. These take the form of a discussion, with a sequence of comments. OSLC Core provide a common way for applications to easily add to a comment to a discussion thread or navigate a discussion thread.

Error responses from HTTP request often take the form of HTML pages intended for a human to read, even though these requests are often initiated from applications that don't have a human actively monitoring it. OSLC Core defines a consistent way to request error responses of a certain format, and a prescribed interaction model that helps clients better handle errors automatically.

Consider a user interface for a query builder that allows users to build queries about test cases. It is natural for the query builder to present the user with a list of the properties that apply to test cases that could be used in the query. Suppose the user wants to build a query that returns all the requirements that are validated by a test case. The query builder should describe the available properties from the point of view of the test case. This implies that the query builder should describe the inverse relation asserted by any triple that has the test case as an object. In this example, the query builder should describe assertions of the form {requirement oslc_rm:validatedBy test case} as {test case validates requirement}.

Some RDF properties express relations or links between subject and object artifacts. If a change in state of subject and/or object of a triple may result in the assertion becoming invalid, the link may be seen to represent a dependency. OSLC Core provides property oslc:impactType as a means of defining the dependency represented by an RDF property.

Resource Shape

The shape of an RDF resource is a description of the set of triples it is expected to contain and the integrity constraints those triples are required to satisfy. Applications of shapes include validating RDF data, documenting RDF APIs, and providing meta-data to tools, such as form and query builders, that handle RDF data. OSLC Core uses shapes to:

Constraints on OSLC Core and Domain resources SHOULD be described using [[!ResourceShapes]] which is included as part of the OSLC Core multi-part specifications. Servers MAY use other constraint languages such as [[SHACL]] to define resource constraints.

Defining Enumerations

Some property values are are characterized by a limited set of enumerated values. The type for these property values is called an enumeration in many modeling and programming languages, while the values are called enumeration literals. RDF does not define a specific way of defining enumerated types and enumeration literals. As a result, different vocabularies may take different, but equally valid approaches. In order to foster interoperability and integration, OSLC Core provides a recommended approach for defining enumerated types and enumeration literals. This approach is used in defining the OSLC Core vocabulary terms.

Enumerations in an OSLC vocabulary should be defined as an RDF class. Enumeration literals are the URIs of individuals of that class. For example, consider an enumeration called "Color" that has enumeration literals {red, yellow, green, blue} (using Java notation). Color would be defined as an RDF class and the enumeration literals would be individuals of that class. A color property is defined and then used to assert that the color of myCar is blue.

# Color enumeration
Color
    a rdfs:Class ;
    rdfs:label "Color" ;
    rdfs:comment "The class of possible color values." .

# Color enumeration literals
red
    a Color ;
    rdfs:label "red" .

yellow
    a Color ;
    rdfs:label "yellow" .

green
    a Color ;
    rdfs:label "green" .

blue
    a Color ;
    rdfs:label "blue" .

# A Color property
color
    a rdf:Property ;
    rdfs:label "color" ;
    rdfs:comment "Used to specify the color of a resource".

# Asserting the color of a resource
myCar color blue.
        

Enumerations can be open or closed. Open enumerations allow additional enumeration literals to be added as needed. Closed enumerations have a fixed set of enumeration literals that is not intended to be extended. Resource shapes can be used to constrain enumerations to a specific set of values. Notice in the example above that the color property did not specify its rdfs:range. This keeps the enumeration completely open to any set of individuals. OSLC prefers to use resource shapes to constrain resources for particular usages, leaving them open for extension for other, possibly unanticipated usages.

A shape can be used to constrain the Color enumeration for a specific purpose. For example, the color of lights in a traffic light should be constrained to exactly red, yellow and green.

# Create a constraint on Color for traffic lights
TrafficLightConstraint
    a oslc:ResourceShape ;
    oslc:describes fhwa:TrafficLight ;
    determs:title "Establish constraints for traffic light colors" ;
    oslc:property colorConstraint .

colorConstraint
    a oslc:Property ;
    oslc:name "color" ;
    dcterms:description "The colors for a traffic light as specified by FHWA."
    oslc:propertyDefinition color ;
    oslc:occurs oslc:Exactly-one ;
    oslc:range Color ;
    oslc:allowValue red, yellow, green ;
    oslc:readOnly "false" ;
    oslc:representation oslc:Reference ;
    oslc:valueType oslc:Resource .
        

TrafficLightConstraint defines a constraint associated with the vocabulary term fhwa:TrafficLight. The constraint has one property, colorConstraint whose oslc:propertyDefinition is the color RDF property. The oslc:range for the colorConstraint is set to Color, meaning the value of the applicable property is constrained to be of rdf:type Color. The oslc:allowedValue property further constrains the values to be red, yelow, or green. If the oslc:allowedValue were not specified, then the TrafficLightConstraint would allow the enumeration to be open.

A completely different shape constraint could be used for colors that represent the status of a risk mitigation in a software development project.

Common Properties

Unlike the rest of the Core specification, these properties change and grow as new common properties are added by the Core TC. The properties that we list here are available for use in OSLC domain specifications when defining OSLC resources, but this does not mean that they are required to be in OSLC resources. OSLC domain specifications decide which properties are allowed and required for resources needed to realize their use cases. The OSLC common properties include properties defined in other standard vocabularies including:

Properties on Any Resource

Person Properties

Implementation Conformance

Changes to the OSLC Core Vocabulary MUST be approved by the OASIS OSLC Core TC. The OSLC Core Vocabulary is assigned the namespace URI of the http://open-services.net/ns/core#.

Domain TCs and other extensions MUST contribute their vocabulary terms in a namespace which is assigned to them as an authority.

OSLC Core, domain and other extensions SHOULD reuse existing vocabulary terms from stable vocabularies such as [[!DC-TERMS]], RDF [[!rdf11-concepts]], RDF Schema [[!rdf-schema]], [[!FOAF]], [[skos-reference]] and OSLC. New vocabulary terms should only be created when there is no clear existing choice available. See the [[!LDP]] similar clause on reuse.

See for details on common property terms.

Discussion

Shape: Discussion

It is common to collect a series of comments on a lifecycle resource, often referred to as a discussion. For example: tasks, bug reports, requirements, assets and so on, are often collected across various types of resources such as project. A project might reflect the planning of work to deliver a product that realizes the requirements as validated through test cases and bug reports. Discussions allow users to collaborate with each other for more efficient and effective delivery. This Discussion resource definition provides a minimal shape describing the needed properties.

Shape: Comment

Used in conjunction with Shape: Discussion to provide a minimal resource definition for a collection of comments.

See for details on discussion property terms.

Errors

Implementation Conformance

When an OSLC Server incurs an error, it is RECOMMENDED that useful information be provided to clients in the body of the HTTP response.

OSLC Servers SHOULD use the Error resource defined below as the basis for forming error responses.

OSLC Servers SHOULD return an Error resource using the same representation format requested by the client via the HTTP Accept request header. [[!HTTP11]]

OSLC Clients SHOULD treat the oslc:statusCode as a String that starts with digits, but may contain non-digit text.

Shape: Error

Used when servers may need a consistent shape to communicate error messages.

Shape: ExtendedError

Additional details about an error the server had when processing the request.

See for details on error property terms.

Terms for describing vocabularies

Inverse Labels

The W3C RDF Schema vocabulary defines the vocabulary annotation property rdfs:label. This property is intended to provide a human-readable description for a resource’s name. It is often used to provide a label for RDF properties. [[LinkGuidance]] discourages the creation of inverse predicates. However, there is still a need for a property, like rdfs:label, to specify an inverse label for a predicate.

For example, consider the OSLC Requirements Management (RM) property oslc_rm:validatedBy. When used as the predicate of a triple, this property is used to assert that the subject resource, e.g. a Requirement, is validated by the object resource, e.g. a TestCase. The rdfs:label for this property is “validatedBy”.

Now consider the user interface of a query builder that allows users to build queries about TestCases. It is natural for the query builder to present the user with a list of the properties that apply to TestCases. Suppose the user wants to build a query that returns all the Requirements that are validated by a TestCase. The query builder should describe the available properties from the point of view of the TestCase. This implies that the query builder should describe the inverse relation asserted by any triple that has the TestCase as an object. In our example, the query builder should describe oslc_rm:validatedBy as “validates”.

The oslc:inverseLabel property provides a human-readable label for the inverse of the subject property.

For example, the following triple (in Turtle notation) would be added to the OSLC RM vocabulary:

            oslc_rm:validatedBy oslc:inverseLabel "validates".
            

It should be noted that the use of inverse labels is independent of the existence of explicit RDF inverse properties. However, if an inverse property is defined by some vocabulary, then a consistent label should be used in order to avoid confusion. In general, it is good practice to avoid the creation of inverse properties since it creates redundant information and complicates SPARQL queries. Instead, a single property should be wherever possible and it should be given an inverse label in order to describe the property from the perspective of the object.

For example, the OSLC Quality Management (QM) vocabulary defines two properties that are approximately inverse to oslc_rm:validatedBy. These are oslc_qm:validatesRequirement and oslc_qm:validatesRequirementCollection. In this case the choice of inverse label “validates” for oslc_rm:validatedBy is consistent with the actual labels of the inverse properties, namely “validatesRequirement” and “validatesRequirementCollection”.

Traceability and Impact type

Some RDF properties express dependency relations between artifacts, and it is often very valuable to trace the impact of a change in an artifact to those artifacts that depend on it directly or indirectly. The concept of dependency is very general. For example, the concept of trace relations is described in SysML: “A generic trace requirement relationship provides a general-purpose relationship between a requirement and any other model element. The semantics of trace include no real constraints and therefore are quite weak.”

As a general guideline, if any assertion involving a given predicate may become invalid if the state of either its subject or object resources change, then we may legitimately regard that predicate as expressing a dependency relation, in which case it may be useful to explicitly describe the nature of the dependency.

An assertion describes a link between subject and object resources whose name is the property or predicate of the assertion. A dependency relationship may be in the same direction as the link, the opposite direction, both directions, or the link may not represent any dependency whose impact might need to be assessed.

For example, in assertions such as {requirement validatedBy testcase}, it may be important to assess the impact of a change in the requirement or a change in the testcase. Typically test cases are updated to reflect changes in requirements in order perform the correct validation. So in this case, property validatedBy would introduce impact that follows the link, from the subject requirement to the object testcase. However, if a team is doing test-driven development, they may treat test cases as formal, executable specifications of requirements and the requirement is simply an informal description of the test case. In this case, the team might consider the impact to be opposite of the link, from the testcase to the requirement.

The property oslc:impactType asserts that the subject property is a dependency relation and gives the direction of impact. The resources oslc:FollowsLink and oslc:OppositeLink identify whether the impact follows the direction of the assertion (subject to object), or the opposite direction (object to subject). oslc:SymmetricImpact describes a symmetric dependency relation in which the property represents a dependency from both subject to object and object to subject. oslc:NoImpact indicates the predicate does not represent any dependency between the subject and object resources.

For example, the following triple (in Turtle notation) would be added a vocabulary to indicate test cases are dependent on requirements:

ex:validatedBy oslc:impactType oslc:FollowsLink .

The same dependency could also be described from the perspective of the test case. In this case, the dependency is opposite of the validatesRequirement predicate:

ex:validatesRequirement oslc:impactType oslc:OppositeImpact .
ex:validatesRequirementCollection oslc:impactType oslc:OppositeImpact.

Discovery

Vocabulary terms are discovered via published vocabulary documents at the OSLC Core namespace and shapes at advertised URLs.

Terms

Change History

Revision Date Editor Changes Made
01 07/06/2016 Jim Amsden CSD was approved and published.
02 12/16/2016 Jim Amsden Added oslc:error common property to associate oslc:Error resources with any resource.
02 12/16/2016 Jim Amsden Added dcterms:references as a common property.
02 12/16/2016 Jim Amsden Added the created, references, identifier properties to oslc:Error.