OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

oslc-core message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Contributing OSLC vocabulary, URI and links guidance documents

OSLC Core TC members,

Per our last meeting [1] I reviewed the set of guidance documents that the OSLC Core WG [2] will contribute to this TC as the proposed foundation for future guidance work.  I am sending this on behalf of the OSLC Core WG [2].

These 3 documents and supporting material are:

1. "OSLC Core URI Naming Guidance.html"
Original location: http://open-services.net/wiki/core/OSLC-Core-URI-Naming-Guidance/

2. "Links.html"
Original location: http://open-services.net/wiki/core/Links/

3.  "Defining Vocabs 3.0.html"
Original location: http://open-services.net/wiki/core/Defining-Vocabs-3.0/
Supporting attachment: "coreV3Sample.ttl"

[1] - https://wiki.oasis-open.org/oslc-core/Meetings/Telecon2013.11.26
[2] - http://open-services.net/workgroups/core/

Thanks,
Steve Speicher
IBM Rational Software
OSLC - Lifecycle integration inspired by the web -> http://open-services.net

Status: Approved guidance

This document gives guidance on how to define URIs for specifications and the expected usage of them.

Contents

Guidelines for Defining URIs

When there is a need to identify anything in OSLC, use a URI. Using URIs allows everything to be linked together.

There are exceptions to this rule. Some examples are:

Domain base URIs

The guidance includes defining a namespace URI structure that matches: http://open-services.net/ns/{domain}#

In some cases, there may be sub-domains within a domain. Then the pattern becomes: http://open-services.net/ns/{primary-domain}/{sub-domain}#

So for the CM 2.0 namespace URI, we’ll have: http://open-services.net/ns/cm#

and for the Core namespace URI, we’ll have: http://open-services.net/ns/core#

Additional guidance

Resource naming Simply append the name of the resource to the end of the domain URI.

For example, to define ChangeRequest in CM, it will become: http://open-services.net/ns/cm#ChangeRequest

Property URIs Append property name to domain URI.

For example, to add the serviceProvider property to Core, it will become: http://open-services.net/ns/core#serviceProvider

Usage Identifiers These are used within various services to identify in what scenarios the service (creation factory, query capabilities, delegated UI dialogs, etc) could be used by a provider.

An example for CM having a “My ToDo” list, http://open-services.net/ns/cm#toDo

Process for publishing meaningful content at URIs

These are rooted at open-services.net at http://open-services.net/ns using the approach outlined in http://www.w3.org/TR/swbp-vocab-pub/ Best Practice Recipes for Publishing RDF Vocabularies Recipe #3.

RDF Content

Provide an RDF/XML document that defines the namespace and each URI in the vocabulary. For an example, see cm.rdf.

Each URI in the vocabulary should appear as the rdf:about attribute on one of the following types of element:

The OSLC guidelines recommend the use of hash URIs. The following information should be included:

Do not use rdfs:domain as it has unwanted inferencing implications. Limit the use of rdfs:range.

HTML Content

Since OSLC recommends hash URIs, the namespace should redirect to an wiki page that has a section names for each fragment, i.e. local name. This wiki page should then link to the location in the wiki citied by the rdfs:seeAlso property.

A suitable wiki page can be conveniently generated from the RDF/XML vocabulary file, e.g. myvocabulary.rdf, by an XSLT transformation such as File:Vocabulary.xsl. You can use Ant to execute the XSLT transform. See File:build.xml for example. After you generate the HTML, e.g. myvocabulary.html…:

  1. Attach it and the RDF file to the wiki on the File Uploads page. (The name of the page in each wiki is Special:Uploads)
  2. After you upload the file, copy the file name.
  3. In your Vocabulary page, include the html content with the following code: %%INCLUDE:myvocabulary.html%% (changing the file name accordingly). Be aware of the following restrictions:

See the OSLC Performance Monitoring Vocabulary for an example on the new wiki system, and the OSLC Core Vocabulary for an example on the legacy system.

See Vocabulary index for a list of all published vocabularies (updated manually).

References

Guidance on Linking Resources

This working document discusses OSLC guidance on how to represent, manage and interpret links between OSLC resources, and in general any linked data resources.

OSLC version 2.0 provided guidance on linking. This document will provide an updated set of guidance to be included as part of the Core 3.0 set of specifications.

Design Goals and Constraints

  1. Keep links simple.
  2. The term “Link” is a relationship between two resources when one resource (representation) refers to the other resource by means of a URI.
  3. Links are uni-directional.
  4. Links are represented in RDF with a single statement (triple).
  5. A link triple may be stored in any graph. It may be stored in the graph of the subject URI, the object URI, or some other arbitrary graph.
  6. The RDF representation of a resource is a general graph. The graph may have statements about the resource or other resources. The resource graph provides the context (which graph is asserting the statement) of the triple. The decision of which resource graph to insert a triple should be consistent with the normal lifecycle of the resource.
  7. Avoid creating aliases (multiple names for same meaning) for link predicates (true for properties in general).
  8. Promote the reuse of existing vocabularies.
  9. Do not rely on OWL and RDFS inferencing.
  10. Predicate URIs should be directly resolvable and its properties include an rdfs:label that is used in user interfaces. There may be multiple rdfs:label for various languages, where the format indicates how to represent associated encoding, see RDF plain literal.
  11. Properties on a link can be stored using reified statements, however do NOT use reified statements to cache information about subject or object resources. They should only represent properties of the link itself.
  12. Avoid caching resource information outside of the service provider that owns that information. If caching is used, it should be treated like HTTP caching.
  13. To improve performance, minimize HTTP message flows.
  14. Maintain alignment with principles in the Linked Data Platform.
  15. Maintain alignment with the Core 3.0 guidance on vocabularies.

HTTP resource and RDF resource

A resource accessible with an HTTP URI using the standard HTTP methods (HEAD/GET/PUT/DELETE) is considered an HTTP resource. It may contain a graph of RDF data, whose subject URI may or may not include the HTTP resource URI. In the absence of named graphs in the resource, consider all the statements part of the graph identified by the HTTP Request-URI. An HTTP resource has an ETag and a Last-Modified date. These values apply to the graph, not necessarily to the HTTP resource. Most of the time the triples in the graph have the same subject URI as the HTTP resource URI.

An RDF resource is simply a URI, about which statements can be made. When we refer to an RDF resource, we are talking about the subject URI shared by a set of triples. Hence, a graph may refer to more than one RDF resource.

It is possible to assert statements about a subject URI yet store the statements at a different URI than the subject. This might be the case when the user does not have rights to edit the HTTP resource

Requirements

A set of requirements that the link guidance will satisfy. The link guidance statements to be part of the OSLC Core 3.0 set of specifications shall ensure that the following requirements could be satisfied by OSLC service provider and client implementations.

  1. Users can create links from one HTTP resource to another from any resource’s context (i.e. user interface native to the resource’s origin).
  2. When viewing an HTTP resource in a user interface, the user wishes to see all the links that the resource is either a subject or an object of.
  3. User interfaces show links with human readable link types, and human readable labels (oslc:shortTitle, or dcterms:title) for both the subject and object of the link.
  4. User interfaces should use human-readable link role names. Role names may vary for subject, object and link type, but not by link instance (i.e., there will not be support for two links of the same type to have different role names).
  5. Additional properties can be stored on the link itself, however they should describe the link and NOT the object or subject.
  6. If a user does not have view rights to a graph that a link triple is stored in the link is not visible to the user.
  7. Conceptually a link appears as a property of an RDF resource. This property is normally stored in the graph identified by the subject URI, but it may be stored anywhere. When a client GETs a URI used as the subject URI in an RDF triple, the server returns the entire graph stored at that URI. This graph is the HTTP resource. ETag and Last-Modified headers represent HTTP resources. A HTTP resource is a single graph that may or may not contain all the properties of the RDF resource with the same subject URI.
  8. When a link is created or edited the subject RDF resource’s dcterms:modified and dcterms:contributor properties should change. However if the link is managed in some other graph, the service provider might not know to change those property values. Clients should be aware that those properties might not be conceptually accurate across all graphs in all service providers.
  9. Any system of OSLC service providers should provide a way/mechanism for a client to get all links to and from a given RDF resource.

Use Cases

  1. Find all links - A client finds all the links that a resource is either the subject or object of.
  2. Create link - A client creates a link from a resource to another
  3. Create link in other resource - A client creates a link from a resource that it does not have edit rights on, to another resource that it does.

Additional use cases to be discussed

  1. As a administrator, I should be able to restrict what links can be made between what resources, so that I can enforce a consistent information architecture.

OSLC Core 3.0 Linking Guidance

  1. The link (statement) should be stored with a single document/graph that asserts the relationship.
    1. In cases where there are multiple and possibly conflicting assertions have been made, an application may have domain knowledge of which source (assertion) it has more confidence in.
  2. Link predicates should be directly resolvable.
  3. Clients should not make assumptions about the type or properties of a resource that is the target of a link based solely on the link predicate and the rdf:type of the subject resource.
  4. When absolutely necessary properties can be associated with a link statement itself using reified statements. However these properties should not be used to cache or store properties about the subject or object resources. They should only store properties about the link itself, not the resources.
  5. When defining a new vocabulary with link types, there should be exactly one predicate for each link type concept. That is, avoid defining two different link predicates representing the same meaning, with just the subject and object reversed (e.g. validates / validatedBy ).
  6. Clients should be aware that links may be stored in other graphs. Clients wishing to get all links to/from a given resource (or set of resources) may use query solution. For example, solutions such as a central index, SPARQL endpoints, OSLC Simple Query Syntax could be used.
<

Status: Working document, not approved

This page is intended to pull together the requirements and discussion on how vocabularies should evolve in the future for OSLC.

Background

Vocabularies in V2 are defined by defining resource tables in specifications. These tables follow a common format and indicate both the model of RDF Classes and expected properties, as well as constraints that are found on resources for various scenarios. The scenarios aren’t always clear and sometimes a bit overloaded (create, read, update, query). It is best practice to resource vocabulary terms, though often times the properties are tightly defined within the context of the resource type (RDF Class) that they are expected to represent. This assumption leads to limiting the ability to reuse these.

Proposal

Separate the vocabulary term definition from the resource definition. This proposal leverages learning from the FOAF vocabulary work

Vocabulary term definition:

See example coreV3Sample.ttl

Resource types defined in Shapes based on scenarios:

The specification documents (and other material) can be generated from this information. The RDF Schema and the OSLC Resource Shapes become the normative definition of terms and resources.

References

TBD

Attachment: coreV3Sample.ttl
Description: Binary data

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]