0
$\begingroup$

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.

$\endgroup$
  • $\begingroup$ If you are writing the documentation for a JSON API then the term schema is not too correct: you should use "object" instead (because {"name":"...","age":...} is a JSON object) and describe the object. Furthermore "schema for an API" is not correct: remember that API stands for Application Program Interface and usually is a set of functions/structures/constants/objects/methods. So you must also clarify what you mean with "a JSON API that always returns a particular structure" (do you mean every function in the API?). If you want I can expand this comment. $\endgroup$ – Vor Nov 22 '13 at 19:09
3
+100
$\begingroup$

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)

$\endgroup$
  • $\begingroup$ this is more an implementation/web-oriented question/answer relevant to stackoverflow, without a general definition of "schema" in computer science terms.... $\endgroup$ – vzn Nov 24 '13 at 0:43

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.