Document status: For review

Simplified Maintenance Procedure

Minor additions to the RDL can be handled in a faster and easier way through these simplified maintenance procedures. There are three steps to this procedure. First there are a number of prerequisites that the submitter must adhere to. Then there is a verification and submitting step followed by a 14 day window for review in which registered users may post comments and the submitter can respond and make changes to the submitted reference data.

Prerequisites

  1. Only new reference data items
  2. Max 50 reference data items
  3. Simplified use of 15926-2

Details

1. Only new reference data items

A new reference data item is an RDF node set as a subject in a list of triples.

rdl:newItem	a			p2:ClassOfInanimatePhysicalObject;
  		rdl:hasDesignation	"NEW ITEM"@en^^xsd:string

With new reference data items it is forbidden to add predicates to existing subjects in the RDL and it is forbidden to use 15926-2 to add a classification or a specialization to an existing item in the RDL.

# adding a new entity type to an existing RDL item is forbidden
rdl:RDS327239		a			p2:ClassOfArrangedIndividual;

# adding a new superclass to an exisitng RDL item is forbidden
rdl:newSpecialization  	a       		p2:Specialization ;
        		p2:hasSubclass    	rdl:RDS327239 ;
        		p2:hasSuperclass  	rdl:newItem ;

# adding a new classifier to an exisitng RDL item is forbidden
rdl:newClassification  	a       		p2:Classification ;
        		p2:hasClassified    	rdl:RDS327239 ;
        		p2:hasClassifier  	rdl:newItem ;

New reference data is allowed to be in the hasSubclass position in any specialization relationship or in the hasClassified position of any classification relationship. New reference data is also allowed to be in the hasSuperclass position or the hasClassifier position when the opposing position is filled with another new reference data item.

# making a new item a subclass of an existing item is allowed and recommended
rdl:newSpecialization  	a       		p2:Specialization ;
        		p2:hasSubclass   	rdl:newItem  ;
        		p2:hasSuperclass  	rdl:RDS327239 ;

# making a new item the superclass of another new item is allowed and recommended
rdl:newSpecialization  	a       		p2:Specialization ;
        		p2:hasSubclass  	rdl:anotherNewItem  ;
        		p2:hasSuperclass  	rdl:newItem ;

2. Max 50 reference data items

An item is measured as a RDF subject that is not typed as either p2:Specialization or p2:Classification. All other RDF subjects count. The limit is 50 inclusive.

3. Simplified use of 15926-2

In order to simplify the needed verification and validation there is a limit to the allowed relationships and predicates that can be used.

Allowed 15926-2 relationships:

  • Classification
  • Specialization

Allowed predicates:

  • rdl:hasDesignation
  • rdl:hasDefinition
  • rdl:defaultRdsId
  • rdf:type with object being a 15926-2 entity type
  • rdfs:label

The following predicates will be set automatically:

  • rdl:hasCreationDate is set to now.
  • rdl:hasStatus is set to "Proposed"

Creating a request package

The request package is the official package that is delivered to PCA containing the reference data items to be added together with contact details and a proof of verification.The package must be a zip file containing the following files:

  1. referenceData.ttl
  2. readme.txt
  3. verificationReport.txt

1. referenceData.ttl

All reference data items must be contained in this file, serialized as RDF/TTL encoded as UTF-8.

2. readme.txt

This file must contain the contact details for the request encoded as UTF-8

Name of company: YOUR COMPNAY NAME HERE 
Name of contact person: CONTACT PERSON NAME HERE 
Email of contact person: [email protected] 
Description of content: THIS DESCRIPTION SHOULD BE A FAITHFUL DESCRIPTION OF THE
CONTENT AND WILL BE SHOWN TO EXTERNAL USERS AS THE TEXT DESCRIBING THE SUBMITTED
REFERENCE DATA. THIS DESCRIPTION MAY BE MULTI-LINE AND CAN CONTAIN BOTH LOWERCASE
AND UPPERCASE LETTERS AS WELL AS PUNCTUATION AND NUMBERS. 

3. verificationReport.txt

Upload the referenceData.ttl file to the automatic verification system. Click to download the verificationReport.txt file. This file contains a signature that links the contents of the referenceData.ttl file to the results of a valid verification. Any subsequent changes to referenceData.ttl will invalidate the report.

TODO: Verification systems is still under development and a link will be posted here once it is up and running.

Post request

After review by the PCA staff the referenceData.ttl file will be uploaded to http://staging.data.posccaesar.org. A minimum delay of 14 days is required to allow for comments before moving the referenceData.ttl file into production.

Any registered user may comment on the submitted reference data. Comments are graded as trivial, major or blocker. All comments require a response from the reference data submitter. The minimum delay of 14 days will be extended so that there is a minimum of 3 days to allow for feedback to responses on comments.

A comment will be considered resolved once the reference data submitter has responded. It will go back to unresolved if the commenter posts another comment.

The submitted reference data will move into production once the following criteria are met:

  • All initial comments have gotten a response
  • All major comments have been taken into consideration
  • All blocker comments are in the resolved phase

PCA will help mediate any blocker comments that can not be resolved.

Post request change handling

The submitter may need to make changes to the submitted content after the initial request package. Such changes must be submitted as a Post Request Package (zip) with the following files:

  1. referenceData.ttl
  2. verificationReport.ttl
  3. changes.json

The two first files must meet the criteria specified in the initial request package while the last file (changes.json) must be on the following format and encoded as UTF-8:

[
	{ //this is an object for handling a change description
		'defaultRdsId':'YOUR DEFAULT RDS ID HERE' , 
		'changeDescription':'YOUR CHANGE DESCRIPTION HERE'
	} ,
	
	{ //this is another
		'defaultRdsId':'YOUR DEFAULT RDS ID HERE' , 
		'changeDescription':'YOUR CHANGE DESCRIPTION HERE'
	} //take care that there is no trailing comma
]

A tool for generating this format can be found here: http://posccaesar.org/change-generator/#/

Once reviewed by the PCA staff the changes will be pushed to the staging endpoint and become visible to users. The description of the changes will be made visible in the comments system.

The review period will be extended by up to 5 days to allow for further comments.

Ending procedure

Once the review process finishes, the submitter must contact PCA to have the new reference data included in the production endpoint. PCA will verify that the review process has proceeded according to the criteria and that all final requirements have been met. The last referenceData.ttl file will then be uploaded to the endpoint at http://data.posccaesar.org .

An entry will be added to the log with a report of the review process and a description of the content.

Home
About PCA
Reference Data Services
Projects
Workgroups