Scope of the next draft

[Henry H. Andrews]

Hi folks,

  The next draft (which we hope to publish by late October) is moving along.  Given available time and people, I'm making some adjustments to the scope (which was pretty casually defined anyway).  Here is what I see right now (in addition to current open PRs and the usual language improvements), feedback is welcome.  I hope to have all of the major PRs filed by if not this weekend then next weekend.  After that:

* Two week minimum open period for PRs that impact implementation

* One month final review:  Unless we find a critical problem, no new proposals, only clarifications and bug fixes

Note that "if"/"then"/"else" is the only mandatory change for validators (there are also optional features and non-validation-impacting changes)

Most major changes are in hyper-schema

DEFINITELY IN (unless something really bogs down):

=========================================

Conditional validation

* if/then/else

* we will get feedback on this before considering adding related or alternative features

Set correct boundaries for Hyper-Schema

* In scope:

* Link serialization format (the LDO) based on RFC 5988bis abstract model

* Target hints and expectations (same scope as other link serializations)

* Connecting LDOs to schemas (“links” and “base”)

* Single resource with links (including target interaction hints)

* Things necessary to write a generic hyper-client that uses the above info

* Out of scope

* Semantic description of the instance (move “media” over with “format”, same optional implementation requirements)

* Meta-data annotations (move “readOnly” and “deprecated” in with “default”, “title”, etc.)

* Any grouping of resources into an API or other unit (API Doc vocab)

* Describing responses other than “targetSchema” (API Doc vocab)

* Application-specific usage information beyond “title”/“description” (API Doc vocab)

* Auth (although auth headers may be included in general header descriptions)

Full support for RFC 5988bis (https://mnot.github.io/I-D/rfc5988bis/#links) abstract model, LDO templatization, common link relations

* Change context URI with “anchor”

* Change context within an instance document that cannot be identified by a URI

* Change template variable resolution start point within an instance document

* Document usage of “collection” and “item” link relations within application/schema+json

BEST EFFORT (we'll do something, but probably not everything related):

========================================================

Decide something about “additionalProperties” confusion and various re-use requests

* Vota-a-rama is underway

* Lots of useful information, no clear winner(s) yet

* Re-use intended to parallel OO coding may belong in the code generation vocabulary

* At minimum, non-viable proposals will get closed

Format

* More formats (whatever achieves easy consensus)

* Format [exclusive]minimum/maximum (if someone gets around to it)

MAYBE (on my wish list, but either very complex or not a lot of demand):

========================================================

machine-comprehensible meta-schema extensions

* Allow implementations to discover that an extended vocab is a superset of a standard vocab

* Common case of adding a few custom extensions but fundamentally using validation or hyper-schema as-is

application/instance+json

* OPT-IN media type for instances.  application/json and all +json still fully supported

* like application/ld+json: it adds nice features, but is not required

* Would allow a dependable instance fragment syntax

* Would allow us to define media type parameters

$ref or similar for re-using partial LDOs

* Harder than it seems at first

* Related to the question of multiple “rel”s per LDO

DEFINITELY OUT:

==============

$data and similar dynamic schema proposals (parametrization, source from DB, etc.)

* Hyper-Schema use cases addressed by alternate proposals

* No progress on core philosophical decision

* No effective advocates with time available

thanks,

-henry