mdTranslator

Extending the mdJSON schema

The mdJSON schema, being based in JSON, may be extended without impacting mdTranslator as long as standard mdJSON elements are not renamed, removed, or relocated. New elements and objects can be added, but they will not be observed by mdTranslator, mdEditor, or any of their readers and writers. This form of extension may be useful in situations where a user needs to save additional elements to describe special data types or is implementing a local version of mdTranslator.

To incorporate new elements into the mdJSON standard, more work needs to be done.

1. Start by posting proposed changed to the schema in a GitHub issue for the mdJson-schemas repository (http://github.com/adiwg/mdJson-schemas/issues). In the issue include:

   • Name and definition of the containing object
   • Rules associated with the containing object
   • Names and definition for all new elements
   • Rules for all new elements
   • A JSON example of the proposed schema change
   • Include an examples of how the elements will be output in each of the writers if necessary.
     
     

   Example issue (#230 mdJson-schemas)

   Class Definition: standaloneQualityReport

    "Reference to an external standalone quality report"
   

   Rules:

   • [ ] optional

   ---

   Element Definitions:

   • reportReference: { citation } "Reference to the associated standalone quality report"
   • abstract: ( character ) "Abstract for the associated standalone quality report"
   • elementReport: [ report ] "An array of quality reports"

   Rules:

   • [ ] reportReference: required
   • [ ] abstract: required

   ---

   mdJson:

   {
     "dataQuality": [
        {
           "standaloneQualityReport": {
              "reportReference": { },
              "abstract": "stand alone abstract",
              "elementReport": [ ]
           }
        }
     ]
   }
   

2. Update and publish mdJson-schemas

3. Update and publish mdTools

4. Add the new objects and elements to mdTranslator's internal object, "/lib/adiwg/mdtranslator/internal/internal_metadata_obj.rb". Objects are added as class methods which can instantiate a new object when building an internal object during a mdTranslator read process. Example of the phone object:

    def newPhone
       {
          phoneName: nil,
          phoneNumber: nil,
          phoneServiceTypes: []
       }
    end
   

5. Add or modify the object in the mdJson test helpers, "/test/helpers/mdJson_hash_objects.rb". For new object place a method to instantiate the object and fill all elements with values. Object elements will be "{}" and array elements "[]". Values should be valid and predictable. String elements are given the element name and objects are loaded only when they are required. In this example "scope" and "citation" are loaded from the "scope" and "citation" methods in this same ruby file. Example:

    # lineage --------------------------------
    def lineage
       {
          statement: 'statement',
          scope: scope,
          citation: [citation],
          processStep: [],
          source: []
       }
    end
   

6. Add or modify mdJson build and add methods in "/test/helpers/mdJson_hash_functions.rb". When custom values need to be set or optional objects need to be filled, create "build" and "add" methods. "build" methods return an object, "add" methods insert an object into a passed-in object. Examples:

   build methods

    def build_date(dateTime, type = 'none')
       hDate = date
       hDate[:date] = dateTime
       hDate[:dateType] = type
       return hDate
    end
   

   add methods

    def add_email(hContact, email)
       hContact[:electronicMailAddress] = [] unless hContact[:electronicMailAddress]
       hContact[:electronicMailAddress] << email
       return hContact
    end
   

7. Extend the mdJson reader to handle the new object and/or elements.

8. Write tests for the mdJson reader extensions and verify they did not cause problems for any other sections of mdJson.

9. Extend the mdJson writer to handle the new object and/or elements.

10. Write tests for the mdJson writer extensions.

11. Extend the HTML writer to display the new object and/or elements. The HTML writer's purpose is to display all that is contained in the internal object.

12. Extend any existing writers that can support the new object and/or elements. This includes modifying their test scripts as well.

13. Run rake with all readers and writers to be sure the extension did not cause any unintended issues.

14. Issue a pull request for the mdJson schema extension.

15. Extend mdEditor to support the new objects and/or elements.

an Alaska Data Integration working group project
Report any issues with this page to feedback@mdeditor.org
Document updated