[Solved]: Precise definition of term: *schema*

ignougroup
Problem Detail: Does the term schema, in the context of describing a structure, refer to the actual structure of the data, or the description of this structure? I.e. can I talk about the schema of an entity without a schema language? For example, suppose I am writing documentation for some JSON API, that always returns a particular structure, say:

{     "name" : "jeroen",    "age" :  28 }

Can I say that the schema for the payload returned by this API includes required values for “name” and “age”? Or does the term exclusively refer to another document that formally describes this structure using a schema language of some sort? In that case, what is another appropriate term to refer to the recurring pattern in the structure? The Github API, has a section titled schema: http://developer.github.com/v3/#schema. However, the word schema is not mentioned in the text itself, nor do they use any schema language. This would suggest that schema is just a general term for the structure/attributes of the output. Unless they consider english as a schema language, in which case the entire page is a schema. Hmmm.

Asked By : Jeroen

Answered By : Vor

In order to write the documentation of the structure of the JSON objects returned from your API you can follow two approaches:

  1. describe the common attributes and of the objects returned by every function of your API; and then for each API function describe the specific attributes (their type, meaning, and example);

    Many APIs that use JSON to exchange data are documented using this approach: e.g. Google APIs for various services, Facebook Graph API, Twitter API, …

    In this case I think it is not correct to use the term “schema”.

  2. or you can give a formal description of the output using a schema definition language like JSON-schema (designed by the IETF) and that plays the same role of the XML schema definition language for XML. But I don’t know if JSON-schema is an established standard (there is an active Google group, but I didn’t find any “notable” example, … ).

    In this case you should provide a valid (json-)schema for the output of each function.

    If you choose this approach, then you should say that name and age are two required properties of the (json-)schemas of the (json-)objects returned by the functions of your APIs (but obviously you should provide the full-schemas, too)

Best Answer from StackOverflow

Question Source : http://cs.stackexchange.com/questions/18181  Ask a Question  Download Related Notes/Documents

Leave a Reply