Skip to content

Spec Roadmap

Jump to bottom
Andrew Berezovskyi edited this page Nov 1, 2018 · 1 revision

Status: 'Under development'

Introduction

Purpose of this page is to layout a plan for execution of specification delivery of OSLC Core 3 within the context of the OASIS OSLC-Core TC.

Approach

OASIS has clear requirements on what it takes to produce Standards and Non-Standards track documents from a TC. There are additional requirements to take these documents beyond "Committee Specifications" to full "OASIS Standards".

Approach is to develop a number of specifications, and supporting documents, and package them as "Core 3.0" and release them together as a "Committee Specification" package. Subsequent post-"Core 3.0" deliverables will most likely take the form of "Core 3.0 Extensions" (or some appropriate name for the package) or "Core 3.1". Though the intent is that with subsequent releases, they are completely backwards compatible to "Core 3.0" and simply additive and discoverable capabilities (much like how HTML5 works).

Completion timeline

See the current completion timeline

Tasks (high-level)

Just a sketch of tasks, incomplete:

  1. define which specs and supporting docs as part of that delivery timeline

    1. Define minimal work products, dependencies, priorities for "3.0" 2014 delivery

    2. In support of 1.1, carve out exact document name and purpose -- work with OASIS staff to reserve in doc repo

  2. assign owners, get work done

  3. get spec tools in place (Word, respec, ???)

    1. Take run at .

    2. Define spec template for Core (and other TCs) -- focusing on componentized specs that can be independently adopted, even without OSLC Core but just LDP)

  4. Produce working drafts per phased plan

    1. Gather use cases and requirements

    2. Look down document name and purpose

    3. Develop initial working draft with outline

    4. Complete working draft, and get informal TC review

    5. Once ready, circulate to TC for comments/review (allow 2 weeks)

    6. Handle comments and seek approval for release as "Committee Specification"

Work products (types)

General TC internal workings process and guidelines

  • Handling of URI assignments across TCs (carving out the open-services.net/ns/* space

    • For OSLC spec authors:

    • Resource design best practices (including naming conventions, property/class design, etc)

    • Evolution of vocab terms and shapes

Public guidelines and best practices (Non-standards track)

  • For implementers of LD and OSLC:

  • Link guidance

  • Resource design best practices (including naming conventions, property/class design, etc)

Specifications (Standards track)

Iterations

The goal is to focus on small chunks of work, deliver it and iterate onto next work product. Iteration ordering is intended to represent priority and dependency, we have not fixed a time to iterations. Currently we are driving towards completion of the specifications by enumerating the set of outstanding issues and resolving them in order of greatest impact to least impact.

The current status of the documents is found here

Deferred from 3.0 The following specifications were deferred from the initial set of documents and will be addressed in a subsequent version of the standard:

  • Actions

  • Automation

Not 3.0 Other things that we might need to have a statement on, reference or use but will NOT be in Core TC in foreseeable future:

  • query syntax (OASIS post-3.0 work)

  • shapes (moving to W3C)

  • TRS (plan for W3C)

Dependencies

OSLC specifications may have needs that are met by other completed or in-progress specifications. It has always been a goal to not reinvent but reuse as much as possible.
Name Description Status Authority
Resource definitions and operations Summary of the HTTP and RDF standard techniques and best practices that used, and anti-patterns avoided, when constructing clients and servers that read and write linked data. W3C Candidate Recommendation W3C LDP WG
Container The resource that allow new resources to be created using HTTP POST and existing resources to be found using HTTP GET. W3C Candidate Recommendation W3C LDP WG
Paging A mechanism for splitting the information in large containers into pages whose representation can be requested incrementally W3C Last Call W3C LDP WG
Shapes and constraints A mechanism for describing the properties that a particular type of resource must or may have. Semantics defined using SPARQL ASK. Considering also how ‘flipped triples’ are handled. OSLC Core 2.0 final spec, W3C WG starting W3C (new), OSLC (open-services.net for 2.0 maintenance)
Tracking resource changes The Tracked Resource Set protocol allows a server to expose a set of resources in a way that allows clients to discover the exact set of resources in the set, to track all additions to and removals from the set, and to track state changes to all resources in the set. OSLC Core 2.0 finalizing spec OSLC (open-services.net for 2.0 maintenance), W3C (future?)
Container filtering URL-based query syntax and semantics defined in SPARQL SELECT, binding SPARQL endpoint to Containers. OSLC 2.0 final spec OSLC (open-services.net for 2.0 maintenance), future?

Unknowns / risks

  • W3C LDP completion

  • contributions from TC participants

  • feedback/comments/issues from TC

Spec Structure

This section will be used to sketch out the key common sections that we expect in specifications. As we have seen, there are a number of common (or even needed) sections across a number of specifications we have developed in the past with OSLC 2.0-flavor specs. Since the 3.0-flavor specs will not be complete profiles but instead thought of as components that can plug into a systems. Therefore, they will lack a lot of the boilerplate language that was seen in 2.0 and rely on references or external profiling mechanisms. Instead, 3.0 specs will simply spec their purpose and how to discover it (and how it might interact with other capabilities/specs). In this way, 3.0 specs (not just from Core) can be easily adopted independently and as-needed.

Outline (sketch)

The sections don't need to have these exact titles but more of a template for the sections:

  1. Introduction - simple paragraph or two introducing the specification, a simple example would be preferred

  2. Terminology - references to common core and LDP terminology + anything new

  3. Motivation - reference to use cases and requirements

  4. Capability - a definition of the new capability in detail, including what resources are needed to support it

    1. Resource Shape - properties associated with a resource

    2. Discovery - how does a client discover this capability

  5. Vocabulary - Appendix - new RDF terms defined by this specification. Should be defined with global context in mind, allowing for reuse in other domains and specs.

Detailed work product file names

There will be various parts (individual capability specs, best practices, etc). There may need to be a decision to NOT publish everything into a single multi-part package. For example, putting a best practice document as its own work product and not as a part so it can independently be updated without having to publish all the parts. Here is the current thinking of planned work products for each TC:

  1. prose spec(s) in HTML and PDF (HTML editable source)

  2. vocabulary document (Required .ttl)

    1. Other forms, which can be machine converted to other forms as needed such as .html, .jsonld, .rdf)

  3. shape documents (Required .ttl)

    1. Other forms like vocabulary documents.

  4. (optionally) JSON-LD context document

  5. supporting documents (non-standards track)

    • Documents such as: Guidance / Best Practices, Primer, Use Case and Requirements, Implementation Reports, etc I think it is fair for each TC to decide which of these is needed AND what is the medium to produce these work products, for example is wiki page good enough or document in TC repo.

Below lists a not-100% accurate mapping of what files (work products) this TC would generate and how it maps to physical folders, files and content types.

specs/
   + oslc-overview.html
   + resource-preview.html
   + links.html
   + common-vocab.html
   + actions.html
   + compatibility.html
   + authentication.html
   + ... 
   + images/
       + (a number of PNG, JPG files supporting specs)
   + vocab/
      + preview.ttl
      + ...
      + generated/
         + core.ttl  (only 1 vocabulary document for all of Core).
         + core.jsonld
         + core.html
         + core.rdf
   + shapes/
      + core-preview.ttl
      + core-compact.ttl
      + core-dialog.ttl
      + ....
   + jsonld-context/
      + compact-context.jsonld
      + ...
supporting-docs/
   + best-practices.html  (non-standards)

Main links

Clone this wiki locally