Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add JSON Schema of extensions, TD minimal validation reference #373

Merged
merged 6 commits into from
Jul 11, 2022
Merged

Add JSON Schema of extensions, TD minimal validation reference #373

Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
96a0fad
Add TD extensions' JSON Schema, reference TD Minimal validation
farshidtz Jul 9, 2022
02d5b0d
Fix TD model import
farshidtz Jul 9, 2022
c01f241
Change TD JSON Schema to v1.1
farshidtz Jul 9, 2022
98165c7
Remove Issue 99 note
farshidtz Jul 9, 2022
ca89e80
Update index.html
mmccool Jul 11, 2022
280e35e
Update index.html
mmccool Jul 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 22 additions & 14 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1514,7 +1514,7 @@ <h4>Creation</h4>
Creation refers to the registration of a new <a>TD</a> inside the directory.
</p>
<p>
The TD object is validated in accordance with [[[#validation]]].
The TD object is validated in accordance with [[[#exploration-directory-api-things-validation]]].
Note that a TD may or may not be generated by the <a>Thing</a> it describes.
For brownfield devices in particular a separate <a>Discoverer</a> process
or service may be required that generates and registers a TD for a <a>Thing</a>
Expand All @@ -1536,7 +1536,7 @@ <h4>Creation</h4>
<span class="rfc2119-assertion" id="tdd-things-create-known-contenttype">
The request SHOULD contain `application/td+json` Content-Type header for
JSON serialization of TD.</span>
The TD object is validated in accordance with [[[#validation]]].
The TD object is validated in accordance with [[[#exploration-directory-api-things-validation]]].
<span class="rfc2119-assertion" id="tdd-things-create-known-td-resp">
Upon successful processing, the server MUST respond with
201 (Created) status.</span>
Expand All @@ -1558,7 +1558,7 @@ <h4>Creation</h4>
<span class="rfc2119-assertion" id="tdd-things-create-anonymous-contenttype">
The request SHOULD contain `application/td+json` Content-Type header for
JSON serialization of TD.</span>
The TD object is validated in accordance with [[[#validation]]].
The TD object is validated in accordance with [[[#exploration-directory-api-things-validation]]].
<span class="rfc2119-assertion" id="tdd-things-create-anonymous-td-resp">
Upon successful processing, the server MUST respond with 201 (Created) status
and a Location header containing a system-generated identifier for the TD.</span>
Expand Down Expand Up @@ -1719,7 +1719,7 @@ <h4>Update</h4>
<span class="rfc2119-assertion" id="tdd-things-update-contenttype">
The request SHOULD contain `application/td+json` Content-Type header for JSON
serialization of TD.</span>
The TD object is validated in accordance with [[[#validation]]].
The TD object is validated in accordance with [[[#exploration-directory-api-things-validation]]].
<span class="rfc2119-assertion" id="tdd-things-update-resp">
Upon success, the server MUST respond with 204 (No Content) status.</span>

Expand Down Expand Up @@ -1763,7 +1763,7 @@ <h4>Update</h4>
but appear in the original TD, that member is removed.
Members with object values are processed recursively.

After applying the modifications, the TD object is validated in accordance with [[[#validation]]].
After applying the modifications, the TD object is validated in accordance with [[[#exploration-directory-api-things-validation]]].
<span class="rfc2119-assertion" id="tdd-things-update-partial-resp">
Upon success, the server MUST respond with a 204 (No Content) status.</span>

Expand Down Expand Up @@ -2033,16 +2033,20 @@ <h4>Listing</h4>

</section>

<section id="validation" class="normative">
<section id="exploration-directory-api-things-validation" class="normative">
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Modified left-over generic ID from when validation section was outside of TDD's API.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good catch, just make sure there are no duplicate ids introduced (including between sections and assertions, they are all in one namespace)

<h4>Validation</h4>
<p>
<span class="rfc2119-assertion" id="tdd-validation-syntactic">
The syntactic validation of TD objects before storage is RECOMMENDED to
prevent common erroneous submissions.</span>
This corresponds to
<a href="https://www.w3.org/TR/wot-thing-description11/#minimal-validation-serialization-json">Minimal Validation</a>
as defined in the WoT Thing Description specification [[wot-thing-description11]].
<span class="rfc2119-assertion" id="tdd-validation-jsonschema">
The server MAY use
<a href="https://www.w3.org/TR/wot-thing-description/#json-schema-for-validation">Thing Description JSON Schema</a>
<a href="https://www.w3.org/TR/wot-thing-description11/#json-schema-for-validation">Thing Description JSON Schema</a>
mmccool marked this conversation as resolved.
Show resolved Hide resolved
to validate standard TD vocabulary, or a more comprehensive JSON Schema to also validate extensions.</span>
The extensions used for <a>Enriched TDs</a> can be validated using [[[#tdd-extensions-jsonschema]]].
</p>
<p>
Additional forms of validation can be added to support various use cases.
Expand Down Expand Up @@ -2092,10 +2096,6 @@ <h4>Validation</h4>
due to the current lack of WoT-specific error types.
</p>
</aside>



<div class="issue" data-number="99"></div>
</section>

</section>
Expand Down Expand Up @@ -2401,9 +2401,8 @@ <h4>API Specification (Thing Model)</h1>
given in this Thing Model
are not normative and are provided for information only.
</p>
<pre class="advisement json">
<div data-include='directory.tm.json'></div>
</pre>
<pre class="advisement json"
data-include='directory.tm.json'></pre>
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is change is to remove an extra line-break from the rendered output.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that I in fact inlined this in the 3-wd publication.


<p class="issue" data-number="82">
Need to confirm if equivalent OpenAPI spec can be easily created out of the TM.
Expand Down Expand Up @@ -2964,6 +2963,15 @@ <h2>CoRE Resource Types Registration</h2>

</section>
</section>

<section id="tdd-extensions-jsonschema" class="appendix">
<h1>JSON Schema for WoT Discovery TD-extensions</h1>
The following JSON Schema specifies the extensions used in <a>Enriched TDs</a>.
It can be used for validating <a>TDs</a> by a <a>TDD</a>
as prescribed in [[[#exploration-directory-api-things-validation]]].
<pre class="advisement json"
data-include='validation/td-discovery-extensions-json-schema.json'></pre>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

will be inlining this in the 3-wd version, data-include is not working sometimes.

</section>

<section id="changes" class="appendix">
<h1>Recent Specification Changes</h1>
Expand Down