

ISSUE-100: Should the JSON-LD API have a "mode": "strict" flag?

From: Manu Sporny <msporny@digitalbazaar.com>
Date: Wed, 11 Apr 2012 16:13:19 -0400
Message-ID: <4F85E5DF.3070300@digitalbazaar.com>

I just had a long conversation with Dave Longley about what we should do
when compaction results in something that the author may not have
intended. The result of the conversation was the proposal for a "mode":
"strict" option that can be passed to API calls like .compact() and
.frame(). Here's the background:

When people request that something is compacted or framed, they will
probably write code against that data structure. For example, to iterate
over a list of items in the case of "@container": "@list", or to perform
math on something they expect to be a native number (via "@type":
"xsd:integer" coercion). The problem comes in when their data contains
something erroneous like "foo", that is to be coerced to an
"xsd:integer", or if their data contains two {"@list": [....]} values.

"mode": "strict" allows them to tell the JSON-LD API if they are okay
with the API taking artistic license when generating output. So, for
example, if somebody states that "abc" should be an "xsd:integer" - the
number 0 is produced in non-strict mode. In strict mode, an exception is
thrown stating that the conversion could not be performed.

In other words, what people put in the context is what they should get
out, and non-strict mode does its absolute best to make sure that when a
number is requested in non-strict mode, that a number is generated...
even if the source data is "abc". If we don't do this, people will have
to write a large amount of branching logic in their code to handle cases
where the coercion failed.

People using the framing API are going to code to the framing structure
that they provide. They don't want their code to check every single
detail (no micro-syntaxes). The people that care about catching errors
in their data will use strict-mode, those that are okay with some data
coercions not happening perfectly will either 1) not care or 2) write
code to catch the cases where data wasn't coerced exactly how they
wanted it to be coerced.

Basically, strict mode means "I am asking for something very specific,
either give me that or throw an exception". Non-strict mode means "make
a best effort of giving me something reasonable (including the expanded
form of things if they cannot be fully compacted/framed)".

-- manu

Manu Sporny (skype: msporny, twitter: manusporny)
President/CEO - Digital Bazaar, Inc.
blog: PaySwarm Website for Developers Launched
Received on Wednesday, 11 April 2012 20:13:45 GMT
