I've been looking into the OData standard and would like to update my services to provide this standard and to consume it. I know that for the XML, it uses the ATOM XML standard so the names of the elements, such as id, title, author, etc. must be that exactly - conform to the Atom standard. The JSON format for OData has different names for their elements. Are those required to be that way or can I have my JSON structure use the same names for it's elements as the Atom XML structure?
An example is the link - in Atom it's called link, with an href and rel attribute. The JSON name for this element is __metadata with the key being uri. It seems like those names are standard and can't change. I'm wondering if the root elements, __metadata, resource, etc. are standard, but maybe the internal elements maybe more flexible. Like the title element for the Atom corresponds to the name element in the JSON structure, could I keep the JSON structure to use title instead of name?
The names mentioned in the started for JSON are part of the standard and can't be changed (otherwise clients won't be able to understand the payload OData JSON). This applies to pretty much anything starting with double underscore (so __metadata, __deferred and so on). Also the value of the _metadata property (or any other _ property) is defined by the standard and should exactly match the standard. There are couple of other places where the names are defined by the standard, just read through it.
The properties which are not defined by the standard are usually treated as OData properties, so those are defined by the model you're exposing through OData (they are the same as the elements under the m:properties element in OData ATOM). So those are somewhat customizable, by changing the OData model, but then you're changing both ATOM and JSON formats.
Related
In any xml file i can say what namespace I refer to using xmlns-attributes to describe the namespace. It is well descibed here: What does "xmlns" in XML mean?
Then I can use a xml schema having a target namespace so that everyone knows that the schema describes that namespace. One question about that is found here: Why do we need targetNamespace?
Using json-schema we can define schemas for json documents. My mental model is that this is roughly equivalent to having a xsd file.
Now, how do I reference the schema in a json object? I can reference a schema using $schema attribute, but how do I declare the name of the schema i develop myself? I dont understand the equivalent of targetNamespace
Researching for writing the question I found the answer. The closest thing of a targetNamespace is the $id attribute. The standard states...
The "$id" keyword defines a URI for the schema, and the base URI that
other URI references within the schema are resolved against. A
subschema's "$id" is resolved against the base URI of its parent
schema. If no parent sets an explicit base with "$id", the base URI is
that of the entire document, as determined per RFC 3986 section 5
[RFC3986].
... which is kind of the mirror image of the leading text for $schema...
The "$schema" keyword is both used as a JSON Schema version identifier
and the location of a resource which is itself a JSON Schema, which
describes any schema written for this particular version. The value
of this keyword MUST be a URI [RFC3986] (containing a scheme) and this
URI MUST be normalized. The current schema MUST be valid against the
meta-schema identified by this URI.
so it is essentially the same thing.
Some things to note, however:
a) you use $schema in a schema to define what schema should be used for defining your own custom schema. It is not stated in the spec that $schema in any kind of object should indicate validation for a schema.
b) You may define in your schema that $schema should be an indication about what schema to use for validation.
c) there are other ways to indicate the schema for data. One such example is using content-type in http headers. Another is to use link http headers.
d) vscode and visual studio both interpret $schema as a reference to a schema for use in validation
The issue has been discussed at the github repo for the spec.
https://github.com/json-schema/json-schema/issues/235
https://github.com/json-schema/json-schema/issues/220#issuecomment-209452992
I'm confused what free-form JSON means. Does it mean you can put any types as values in {}?
I thought all JSON are like that (i.e. {'hi':123, 'abc':{'d':[1,2,3],'e':'yay'}}).
So what does free-form JSON mean. Is this a redundant term? Is there such thing as non-free-form JSON?
What you have just posted looks like a JavaScript object, but it is not valid JSON. JSON has some very strict rules, such as all strings must be in double quotes. See JSON.org
There's no such thing as "free-form"/"non-free-form" JSON as every valid JSON-string must be formatted according to the specific rules mentioned on JSON.org.
It's possible that "free-form" JSON is JSON that has been generated "by hand" meaning that you typed it out manually (error prone). Most languages either have built-in methods, or libraries that are available, that turn native data structures (like multi-dimensional arrays) into valid JSON.
PHP, for instance, has a native method called json_encode.
I'm getting a TimeStampToken (RFC3161) by using a java based client.
I need to store all the information included in TSTInfo in a database, MySql or Oracle.Is there any specific format to store it?
There is no specified format1 for this kind of thing.
But some obvious alternatives spring to mind:
Store the DER-encoded form as a BLOB.
Take the DER-encoded form, base-64 encoded it and store it in a CHAR(n) column.
Create a table with columns to represent each of the fields of the TSSInfo structure ... assuming that you are already decoding it.
Serialize the Java object representation using the Java serialization protocol, XML, JSON, etcetera.
and so on.
1 - Actually, according to Wikipedia, there is an encoding for ASN.1 called XER that is represented using XML.
Note that if you only store the TSTInfo, you lose the signature, which is the whole point of having an RFC3161 token. The TSTInfo without the signature proves nothing!
To preserve its evidentiary property, you really should store the entire timestamp token (which is defined as the signed CMS ContentInfo that wraps the TSTInfo).
In terms of what format to use, probably chapter 3.2 of the RFC3161 specification (https://www.rfc-editor.org/rfc/rfc3161) can be helpful (which is only a suggestion though):
3. Transports
There is no mandatory transport mechanism for TSA messages in this
document. The mechanisms described below are optional; additional
optional mechanisms may be defined in the future.
[...]
3.2. File Based Protocol
A file containing a time-stamp message MUST contain only the DER
encoding of one TSA message, i.e., there MUST be no extraneous header
or trailer information in the file. Such files can be used to
transport time stamp messages using for example, FTP.
So, I would store the DER encoded CMS ContentInfo (not of the TSTInfo) as a BLOB
Is it advisable or not in a RESTful web service to use JSON literal values (string / number) as input parameter in the payload or in the response body?
If I have an endpoint PUT /mytodolist is it OK for it to accept a JSON string literal value "Take out the rubbish" in the request payload (with Content-Type=application/json) or should it accept a JSON object instead ({"value":"Take out the rubbish"})?
Similarly, is it fine for GET /mytodolist/1 to return "Take out the rubbish" in the response body or should it return a proper JSON object {"value":"Take out the rubbish"}
Spring MVC to makes implementing and testing such endpoints easy, however clients have flagged this as non standard or hard to implement. In my point of view JSON literals are JSON, but not JSON objects, so I'd say it is fine. I have found no recommendations using Google.
EDIT 1: Clafirication
The question is entirely about the 'standard', if it allows this or not.
I understand the problem with the extensibility, but one can never design a fully extensible interface IMHO. If changes need to be done, we can try extending what we have in a backwards compatible way, but there will come a time when it becomes messy and an other approach is required - which is commonly handled by versioning the API in one way or another. I find it a fair point even though, because using literals as request/response body immediately becomes inextensible, while coming up with a reasonable one-attribute JSON object does not.
It is also understood that some frameworks have problems with handling JSON literals, this is the origin of this question. The tool I used happened to support this, so I thought this was all right, but the front-end library did not.
Still, what I am intending to find out right now, is if using JSON literals is according to the de-facto standard (even if it is a cornercase) or not.
I would recommend to use JSON object always. One reason is that for Content-Type application/json people expect something staring with "{" and not all frameworks will handle json literals properly. Second reason is that probably you will add some additional attributes to you list item (due date, category, priority, etc). And then you'll break backward compatibility, by adding new field.
It may be acceptable in the context of your example, but keep in mind that unambiguous interfaces are easier to use and that will encourage adoption.
For example, your interface could interpret "Take out he rubbish" as the same as {task:"take out the rubbish"}, but once you add additional properties (eg "when" or "who") the meaning of a solitary string in the request becomes ambiguous. It's inevitable that you'll add support for new properties as your interface matures.
I am unable to find a reference to this error exactly, but YAML 1.2 says it's a JSON superset, and if I use tab characters in a JSON it treats it like an error.
e.g.
"root": {
"key": "value"
}
(Online validation here says that '\t' that cannot start any token)
I know why YAML historically disallows tabs, but how can I interpret this in the context of JSON-superset?
(e.g. Is YAML not an actual superset or does JSON also disallow tabs? Or the spec does allow for tabs in this case but the implementation is not there yet?)
Thanks.
Tabs ARE allowed in YAML, but only where indentation does not apply.
According to YAML 1.2 Section 5.5:
YAML recognizes two white space characters: space and tab.
The following examples will use · to denote spaces and → to denote tabs. All examples can be validated using the official YAML Reference Parser.
YAML has a block style and flow style. In block style, indentation determines the structure of a document. The following document uses block style.
root:
··key: value
Validate
In flow style, special characters indicate the structure of the document. The following equivalent document uses flow style.
{
→ root: {
→ → key: value
→ }
}
Validate
You can even mix indentation in flow style.
{
→ root: {
··→ key: value
····}
}
Validate
If you're mixing block and flow style, the entire flow style part must respect the block style indentation.
root:
··{
····key: value
··}
Validate
But you can still mix your indentation within the flow style part.
root:
··{
··→ key: value
··}
Validate
If you have a single value document, you can surround the value with all manner of whitespace.
→ ··value··→
Validate
The point is, every JSON document that is parsed as YAML will put the document into flow style (because of the initial { or [ character) which supports tabs, unless it is a single value JSON document, in which case YAML still allows padding with whitespace.
If a YAML parser throws because of tabs in a JSON document, then it is not a valid parser.
That being said, your example is failing because a block style mapping value must always be indented if it's not on the same line as the mapping name.
root: {
··key: value
}
is not valid, however
root:
··{
····key: value
··}
is valid, and
root: { key: value }
is also valid.
I know why YAML historically disallows tabs, but how can I interpret this in the context of JSON-superset?
Taking the rest of the specifications into account, we can only conclude that the "superset" comment is inaccurate. The YAML specification is fundamentally inconsistent in the Relation to JSON section:
YAML can therefore be viewed as a natural superset of JSON, offering
improved human readability and a more complete information model. This
is also the case in practice; every JSON file is also a valid YAML
file. This makes it easy to migrate from JSON to YAML if/when the
additional features are required.
JSON's RFC4627 requires that mappings keys merely “SHOULD” be unique,
while YAML insists they “MUST” be. Technically, YAML therefore
complies with the JSON spec, choosing to treat duplicates as an error.
In practice, since JSON is silent on the semantics of such duplicates,
the only portable JSON files are those with unique keys, which are
therefore valid YAML files.
Despite asserting YAML as a "natural superset of JSON" and stating that "every JSON file is also a valid YAML file", the spec immediately notes some differences regarding key uniqueness. Arguably, the spec should also note the differences around using tabs for indentation here as well.
Speaking of which, as the validator implied, YAML explicitly prohibits tabs as indentation characters:
To maintain portability, tab characters must not be used in
indentation, since different systems treat tabs differently. Note that
most modern editors may be configured so that pressing the tab key
results in the insertion of an appropriate number of spaces.
This is, of course, stricter than the JSON specification, which simply states:
Whitespace can be inserted between any pair of tokens.
So, to directly answer your questions...
(e.g. Is YAML not an actual superset or does JSON also disallow tabs? Or the spec does allow for tabs in this case but the implementation is not there yet?)
...YAML is not actually a superset, JSON does not disallow tabs, whereas the YAML specification does indeed disallow tabs explicitly.
According to specification tabs were never allowed. So, when JSON is used inside YAML, it is not allowing tabs.
The problem occurs when we think JSON as a pure subset of YAML. But it is not, according to Relation to JSON section in specification, there are some little things, that keeps json from being a pure subset of YAML.
If we are to address those dissimilarities, what we will need is something like YSON, which is also mentioned in the spec.
But fortunately there are some YAML engines that support tabs as indentations. Snakeyml is an example for that.