< draft-ietf-asdf-sdf-08.txt		draft-ietf-asdf-sdf-09.txt >
	ASDF M. Koster, Ed.		ASDF M. Koster, Ed.
	Internet-Draft PassiveLogic		Internet-Draft PassiveLogic
	Intended status: Standards Track C. Bormann, Ed.		Intended status: Standards Track C. Bormann, Ed.
	Expires: 28 April 2022 Universität Bremen TZI		Expires: 10 May 2022 Universität Bremen TZI
	25 October 2021		6 November 2021
	Semantic Definition Format (SDF) for Data and Interactions of Things		Semantic Definition Format (SDF) for Data and Interactions of Things
	draft-ietf-asdf-sdf-08		draft-ietf-asdf-sdf-09
	Abstract		Abstract
	The Semantic Definition Format (SDF) is a format for domain experts		The Semantic Definition Format (SDF) is a format for domain experts
	to use in the creation and maintenance of data and interaction models		to use in the creation and maintenance of data and interaction models
	in the Internet of Things. It was created as a common language for		in the Internet of Things. It was created as a common language for
	use in the development of the One Data Model liaison organization		use in the development of the One Data Model liaison organization
	(OneDM) definitions. Tools convert this format to database formats		(OneDM) definitions. Tools convert this format to database formats
	and other serializations as needed.		and other serializations as needed.
	An SDF specification describes definitions of SDF Objects and their		An SDF specification describes definitions of SDF Objects and their
	associated interactions (Events, Actions, Properties), as well as the		associated interactions (Events, Actions, Properties), as well as the
	Data types for the information exchanged in those interactions.		Data types for the information exchanged in those interactions.
	// A JSON format representation of SDF 1.0 was defined in version		// A JSON format representation of SDF 1.0 was defined in version
	// (-00) of this document; version (-05) was designated as an		// (-00) of this document; version (-05) was designated as an
	// _implementation draft_, labeled SDF 1.1, at the IETF110 meeting of		// _implementation draft_, labeled SDF 1.1, at the IETF110 meeting of
	// the ASDF WG (2021-03-11). The present version (-08) adds URIs as		// the ASDF WG (2021-03-11). The present version (-09) adds a URN
	// alternative measurement unit names, is editorially more self-		// namespace for registered measurement unit names.
	// contained, and uses updated xml2rfc conventions for its plain-text
	// rendering.
	Contributing		Contributing
	Recent versions of this document are available at its GitHub		Recent versions of this document are available at its GitHub
	repository https://github.com/ietf-wg-asdf/SDF (https://github.com/		repository https://github.com/ietf-wg-asdf/SDF (https://github.com/
	ietf-wg-asdf/SDF) -- this also provides an issue tracker as well as a		ietf-wg-asdf/SDF) -- this also provides an issue tracker as well as a
	way to supply "pull requests".		way to supply "pull requests".
	General discussion of this SDF Internet-Draft happens on the mailing		General discussion of this SDF Internet-Draft happens on the mailing
	list of the IETF ASDF Working Group, asdf@ietf.org (subscribe at		list of the IETF ASDF Working Group, asdf@ietf.org (subscribe at
	skipping to change at page 2, line 20 ¶		skipping to change at page 2, line 20 ¶
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF). Note that other groups may also distribute		Task Force (IETF). Note that other groups may also distribute
	working documents as Internet-Drafts. The list of current Internet-		working documents as Internet-Drafts. The list of current Internet-
	Drafts is at https://datatracker.ietf.org/drafts/current/.		Drafts is at https://datatracker.ietf.org/drafts/current/.
	Internet-Drafts are draft documents valid for a maximum of six months		Internet-Drafts are draft documents valid for a maximum of six months
	and may be updated, replaced, or obsoleted by other documents at any		and may be updated, replaced, or obsoleted by other documents at any
	time. It is inappropriate to use Internet-Drafts as reference		time. It is inappropriate to use Internet-Drafts as reference
	material or to cite them other than as "work in progress."		material or to cite them other than as "work in progress."
	This Internet-Draft will expire on 28 April 2022.		This Internet-Draft will expire on 10 May 2022.
	Copyright Notice		Copyright Notice
	Copyright (c) 2021 IETF Trust and the persons identified as the		Copyright (c) 2021 IETF Trust and the persons identified as the
	document authors. All rights reserved.		document authors. All rights reserved.
	This document is subject to BCP 78 and the IETF Trust's Legal		This document is subject to BCP 78 and the IETF Trust's Legal
	Provisions Relating to IETF Documents (https://trustee.ietf.org/		Provisions Relating to IETF Documents (https://trustee.ietf.org/
	license-info) in effect on the date of publication of this document.		license-info) in effect on the date of publication of this document.
	Please review these documents carefully, as they describe your rights		Please review these documents carefully, as they describe your rights
	skipping to change at page 3, line 29 ¶		skipping to change at page 3, line 29 ¶
	5.4. sdfEvent . . . . . . . . . . . . . . . . . . . . . . . . 28		5.4. sdfEvent . . . . . . . . . . . . . . . . . . . . . . . . 28
	5.5. sdfData . . . . . . . . . . . . . . . . . . . . . . . . . 28		5.5. sdfData . . . . . . . . . . . . . . . . . . . . . . . . . 28
	6. High Level Composition . . . . . . . . . . . . . . . . . . . 28		6. High Level Composition . . . . . . . . . . . . . . . . . . . 28
	6.1. Paths in the model namespaces . . . . . . . . . . . . . . 29		6.1. Paths in the model namespaces . . . . . . . . . . . . . . 29
	6.2. Modular Composition . . . . . . . . . . . . . . . . . . . 29		6.2. Modular Composition . . . . . . . . . . . . . . . . . . . 29
	6.2.1. Use of the "sdfRef" keyword to re-use a definition . 30		6.2.1. Use of the "sdfRef" keyword to re-use a definition . 30
	6.3. sdfThing . . . . . . . . . . . . . . . . . . . . . . . . 31		6.3. sdfThing . . . . . . . . . . . . . . . . . . . . . . . . 31
	6.4. sdfProduct . . . . . . . . . . . . . . . . . . . . . . . 31		6.4. sdfProduct . . . . . . . . . . . . . . . . . . . . . . . 31
	7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32		7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32
	7.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 32		7.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . 32
	7.2. Registries . . . . . . . . . . . . . . . . . . . . . . . 32		7.2. IETF URN Sub-namespace for Unit Names
	8. Security Considerations . . . . . . . . . . . . . . . . . . . 32		(urn:ietf:params:unit) . . . . . . . . . . . . . . . . . 32
			7.3. Registries . . . . . . . . . . . . . . . . . . . . . . . 33
			8. Security Considerations . . . . . . . . . . . . . . . . . . . 33
	9. References . . . . . . . . . . . . . . . . . . . . . . . . . 33		9. References . . . . . . . . . . . . . . . . . . . . . . . . . 33
	9.1. Normative References . . . . . . . . . . . . . . . . . . 33		9.1. Normative References . . . . . . . . . . . . . . . . . . 33
	9.2. Informative References . . . . . . . . . . . . . . . . . 34		9.2. Informative References . . . . . . . . . . . . . . . . . 35
	Appendix A. Formal Syntax of SDF . . . . . . . . . . . . . . . . 35		Appendix A. Formal Syntax of SDF . . . . . . . . . . . . . . . . 36
	Appendix B. json-schema.org Rendition of SDF Syntax . . . . . . 39		Appendix B. json-schema.org Rendition of SDF Syntax . . . . . . 40
	Appendix C. Data Qualities inspired by json-schema.org . . . . . 78		Appendix C. Data Qualities inspired by json-schema.org . . . . . 79
	C.1. type "number", type "integer" . . . . . . . . . . . . . . 79		C.1. type "number", type "integer" . . . . . . . . . . . . . . 79
	C.2. type "string" . . . . . . . . . . . . . . . . . . . . . . 79		C.2. type "string" . . . . . . . . . . . . . . . . . . . . . . 79
	C.3. type "boolean" . . . . . . . . . . . . . . . . . . . . . 80		C.3. type "boolean" . . . . . . . . . . . . . . . . . . . . . 80
	C.4. type "array" . . . . . . . . . . . . . . . . . . . . . . 80		C.4. type "array" . . . . . . . . . . . . . . . . . . . . . . 81
	C.5. type "object" . . . . . . . . . . . . . . . . . . . . . . 80		C.5. type "object" . . . . . . . . . . . . . . . . . . . . . . 81
	C.6. Implementation notes . . . . . . . . . . . . . . . . . . 81		C.6. Implementation notes . . . . . . . . . . . . . . . . . . 81
	Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 81		Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 82
	Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 81		Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 82
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82
	1. Introduction		1. Introduction
	The Semantic Definition Format (SDF) is a format for domain experts		The Semantic Definition Format (SDF) is a format for domain experts
	to use in the creation and maintenance of data and interaction models		to use in the creation and maintenance of data and interaction models
	in the Internet of Things. It was created as a common language for		in the Internet of Things. It was created as a common language for
	use in the development of the One Data Model liaison organization		use in the development of the One Data Model liaison organization
	(OneDM) definitions. Tools convert this format to database formats		(OneDM) definitions. Tools convert this format to database formats
	and other serializations as needed.		and other serializations as needed.
	An SDF specification describes definitions of SDF Objects and their		An SDF specification describes definitions of SDF Objects and their
	associated interactions (Events, Actions, Properties), as well as the		associated interactions (Events, Actions, Properties), as well as the
	Data types for the information exchanged in those interactions.		Data types for the information exchanged in those interactions.
	// A JSON format representation of SDF 1.0 was defined in version		// A JSON format representation of SDF 1.0 was defined in version
	// (-00) of this document; version (-05) was designated as an		// (-00) of this document; version (-05) was designated as an
	// _implementation draft_, labeled SDF 1.1, at the IETF110 meeting of		// _implementation draft_, labeled SDF 1.1, at the IETF110 meeting of
	// the ASDF WG (2021-03-11). The present version (-08) adds URIs as		// the ASDF WG (2021-03-11). The present version (-09) adds a URN
	// alternative measurement unit names, is editorially more self-		// namespace for registered measurement unit names.
	// contained, and uses updated xml2rfc conventions for its plain-text
	// rendering.
	1.1. Terminology and Conventions		1.1. Terminology and Conventions
	Thing: A physical item that is also made available in the Internet		Thing: A physical item that is also made available in the Internet
	of Things. The term is used here for Things that are notable for		of Things. The term is used here for Things that are notable for
	their interaction with the physical world beyond interaction with		their interaction with the physical world beyond interaction with
	humans; a temperature sensor or a light might be a Thing, but a		humans; a temperature sensor or a light might be a Thing, but a
	router that employs both temperature sensors and indicator lights		router that employs both temperature sensors and indicator lights
	might exhibit less Thingness, as the effects of its functioning		might exhibit less Thingness, as the effects of its functioning
	are mostly on the digital side.		are mostly on the digital side.
	skipping to change at page 14, line 50 ¶		skipping to change at page 14, line 50 ¶
	The following example declares a set of namespaces and defines cap as		The following example declares a set of namespaces and defines cap as
	the default namespace. By convention, the values in the namespace		the default namespace. By convention, the values in the namespace
	map contain full URIs without a fragment identifier, and the fragment		map contain full URIs without a fragment identifier, and the fragment
	identifier is then added, if needed, where the namespace entry is		identifier is then added, if needed, where the namespace entry is
	used.		used.
	"namespace": {		"namespace": {
	"cap": "https://example.com/capability/cap",		"cap": "https://example.com/capability/cap",
	"zcl": "https://zcl.example.com/sdf"		"zcl": "https://zcl.example.com/sdf"
	},		},
	"defaultNamespace": "cap",		"defaultNamespace": "cap"
	If no defaultNamespace setting is given, the SDF definition file does		If no defaultNamespace setting is given, the SDF definition file does
	not contribute to a global namespace. As the defaultNamespace is set		not contribute to a global namespace. As the defaultNamespace is set
	by giving a namespace short name, its presence requires a namespace		by giving a namespace short name, its presence requires a namespace
	map that contains a mapping for that namespace short name.		map that contains a mapping for that namespace short name.
	If no namespace map is given, no short names for namespace URIs are		If no namespace map is given, no short names for namespace URIs are
	set up, and no defaultNamespace can be given.		set up, and no defaultNamespace can be given.
	3.3. Definitions section		3.3. Definitions section
	skipping to change at page 22, line 40 ¶		skipping to change at page 22, line 40 ¶
	| | strings | string-valued named | |		| | strings | string-valued named | |
	| | | alternatives | |		| | | alternatives | |
	+---------------+----------------+----------------------+---------+		+---------------+----------------+----------------------+---------+
	Table 4: SDF-defined Qualities of sdfProperty and sdfData		Table 4: SDF-defined Qualities of sdfProperty and sdfData
	1. Note that the quality unit was called units in SDF 1.0. The unit		1. Note that the quality unit was called units in SDF 1.0. The unit
	name SHOULD be as per the SenML Units Registry or the Secondary		name SHOULD be as per the SenML Units Registry or the Secondary
	Units Registry in [IANA.senml] as specified by Sections 4.5.1 and		Units Registry in [IANA.senml] as specified by Sections 4.5.1 and
	12.1 of [RFC8428] and Section 3 of [RFC8798], respectively.		12.1 of [RFC8428] and Section 3 of [RFC8798], respectively.
	Exceptionally, if a registration in these registries cannot be		Exceptionally, if a registration in these registries cannot be
	obtained or would be inappropriate, the unit name can also be a		obtained or would be inappropriate, the unit name can also be a
	URI that is pointing to a definition of the unit. Note that SDF		URI that is pointing to a definition of the unit. Note that SDF
	processors are not expected to (and normally SHOULD NOT)		processors are not expected to (and normally SHOULD NOT)
	dereference these URIs; they may be useful to humans, though. A		dereference these URIs; they may be useful to humans, though. A
	URI unit name is distinguished from a registered unit name by the		URI unit name is distinguished from a registered unit name by the
	presence of a colon; registered unit names that contain a colon		presence of a colon; registered unit names that contain a colon
	(at the time of writing, none) can therefore not be used in SDF.		(at the time of writing, none) can therefore not be used in SDF.
			For use by translators into ecosystems that require URIs for unit
			names, the URN sub-namespace "urn:ietf:params:unit" is provided
			(Section 7.2); URNs from this sub-namespace MUST NOT be used in a
			unit quality, in favor of simply notating the unit name (e.g., kg
			instead of urn:ietf:params:unit:kg).
	2. these qualities were included in SDF 1.0, but were not fully		2. these qualities were included in SDF 1.0, but were not fully
	defined; they are not included in SDF 1.1. In 1.next, they will		defined; they are not included in SDF 1.1. In 1.next, they will
	be replaced by qualities to express scaling that are more aligned		be replaced by qualities to express scaling that are more aligned
	with the processes that combine ecosystem and instance specific		with the processes that combine ecosystem and instance specific
	information with an SDF model.		information with an SDF model.
	4.7.1. sdfType		4.7.1. sdfType
	SDF defines a number of basic types beyond those provided by JSON or		SDF defines a number of basic types beyond those provided by JSON or
	JSO. These types are identified by the sdfType quality, which is a		JSO. These types are identified by the sdfType quality, which is a
	skipping to change at page 25, line 18 ¶		skipping to change at page 25, line 18 ¶
	* anyOf		* anyOf
	[I-D.handrews-json-schema-validation] provides a type union called		[I-D.handrews-json-schema-validation] provides a type union called
	anyOf, which provides a choice between anonymous alternatives.		anyOf, which provides a choice between anonymous alternatives.
	What could have been		What could have been
	"anyOf": [		"anyOf": [
	{"type": "array", "minItems": 3, "maxItems": "3", "items": {		{"type": "array", "minItems": 3, "maxItems": "3", "items": {
	"sdfRef": "#/sdfData/rgbVal"}}		"sdfRef": "#/sdfData/rgbVal"}},
	{"type": "array", "minItems": 4, "maxItems": "4", "items": {		{"type": "array", "minItems": 4, "maxItems": "4", "items": {
	"sdfRef": "#/sdfData/cmykVal"}}		"sdfRef": "#/sdfData/cmykVal"}}
	]		]
	in [I-D.handrews-json-schema-validation] can be more descriptively		in [I-D.handrews-json-schema-validation] can be more descriptively
	notated in SDF as:		notated in SDF as:
	"sdfChoice": {		"sdfChoice": {
	"rgb": {"type": "array", "minItems": 3, "maxItems": "3", "items": {		"rgb": {"type": "array", "minItems": 3, "maxItems": "3", "items": {
	"sdfRef": "#/sdfData/rgbVal"}},		"sdfRef": "#/sdfData/rgbVal"}},
	skipping to change at page 32, line 43 ¶		skipping to change at page 32, line 43 ¶
	Fragment identifier considerations: A JSON Pointer fragment		Fragment identifier considerations: A JSON Pointer fragment
	identifier may be used, as defined in Section 6 of [RFC6901].		identifier may be used, as defined in Section 6 of [RFC6901].
	Person & email address to contact for further information: ASDF WG		Person & email address to contact for further information: ASDF WG
	mailing list (asdf@ietf.org), or IETF Applications and Real-Time		mailing list (asdf@ietf.org), or IETF Applications and Real-Time
	Area (art@ietf.org)		Area (art@ietf.org)
	Intended usage: COMMON		Intended usage: COMMON
	Restrictions on usage: none		Restrictions on usage: none
	Author/Change controller: IETF		Author/Change controller: IETF
	Provisional registration: no		Provisional registration: no
	7.2. Registries		7.2. IETF URN Sub-namespace for Unit Names (urn:ietf:params:unit)
			IANA is requested to register the following value in the "IETF URN
			Sub-namespace for Registered Protocol Parameter Identifiers"
			registry, following the template in [RFC3553]:
			Registry name: unit
			Specification: RFC XXXX
			Repository: combining the symbol values from the SenML Units
			Registry and the Secondary Units Registry in [IANA.senml] as
			specified by Sections 4.5.1 and 12.1 of [RFC8428] and Section 3 of
			[RFC8798], respectively (which by the registration policy are
			guaranteed to be non-overlapping).
			Index value: Percent-encoding (Section 2.1 of [RFC3986]) is required
			of any characters in unit names as required by ABNF rule "pchar"
			in Section 3.3 of [RFC3986], specifically at the time of writing
			for the unit names "%" (deprecated in favor of "/"), "%RH", "%EL".
			7.3. Registries
	(TBD: After future additions, check if we need any.)		(TBD: After future additions, check if we need any.)
	8. Security Considerations		8. Security Considerations
	Some wider issues are discussed in [RFC8576].		Some wider issues are discussed in [RFC8576].
	(Specifics: TBD.)		(Specifics: TBD.)
	9. References		9. References
	9.1. Normative References		9.1. Normative References
	[I-D.ietf-cbor-cddl-control]		[I-D.ietf-cbor-cddl-control]
	Bormann, C., "Additional Control Operators for CDDL", Work		Bormann, C., "Additional Control Operators for CDDL", Work
	in Progress, Internet-Draft, draft-ietf-cbor-cddl-control-		in Progress, Internet-Draft, draft-ietf-cbor-cddl-control-
	07, 21 October 2021, <https://www.ietf.org/archive/id/		07, 21 October 2021, <https://www.ietf.org/archive/id/
	draft-ietf-cbor-cddl-control-07.txt>.		draft-ietf-cbor-cddl-control-07.txt>.
			[IANA.params]
			IANA, "Uniform Resource Name (URN) Namespace for IETF
			Use", <https://www.iana.org/assignments/params>.
	[IANA.senml]		[IANA.senml]
	IANA, "Sensor Measurement Lists (SenML)",		IANA, "Sensor Measurement Lists (SenML)",
	<https://www.iana.org/assignments/senml>.		<https://www.iana.org/assignments/senml>.
	[RFC0020] Cerf, V., "ASCII format for network interchange", STD 80,		[RFC0020] Cerf, V., "ASCII format for network interchange", STD 80,
	RFC 20, DOI 10.17487/RFC0020, October 1969,		RFC 20, DOI 10.17487/RFC0020, October 1969,
	<https://www.rfc-editor.org/info/rfc20>.		<https://www.rfc-editor.org/info/rfc20>.
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	Requirement Levels", BCP 14, RFC 2119,		Requirement Levels", BCP 14, RFC 2119,
	DOI 10.17487/RFC2119, March 1997,		DOI 10.17487/RFC2119, March 1997,
	<https://www.rfc-editor.org/info/rfc2119>.		<https://www.rfc-editor.org/info/rfc2119>.
	[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:		[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
	Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,		Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
	<https://www.rfc-editor.org/info/rfc3339>.		<https://www.rfc-editor.org/info/rfc3339>.
			[RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An
			IETF URN Sub-namespace for Registered Protocol
			Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June
			2003, <https://www.rfc-editor.org/info/rfc3553>.
	[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform		[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
	Resource Identifier (URI): Generic Syntax", STD 66,		Resource Identifier (URI): Generic Syntax", STD 66,
	RFC 3986, DOI 10.17487/RFC3986, January 2005,		RFC 3986, DOI 10.17487/RFC3986, January 2005,
	<https://www.rfc-editor.org/info/rfc3986>.		<https://www.rfc-editor.org/info/rfc3986>.
	[RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally		[RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
	Unique IDentifier (UUID) URN Namespace", RFC 4122,		Unique IDentifier (UUID) URN Namespace", RFC 4122,
	DOI 10.17487/RFC4122, July 2005,		DOI 10.17487/RFC4122, July 2005,
	<https://www.rfc-editor.org/info/rfc4122>.		<https://www.rfc-editor.org/info/rfc4122>.
End of changes. 16 change blocks.
	25 lines changed or deleted		59 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/