사물 웹(WoT) 사물 설명 2.0

메타데이터와 인터페이스가 WoT Thing Description으로 설명되는 물리적 또는 가상 엔터티의 추상화이며, 여기서 가상 엔터티는 하나 이상의 Things의 조합이다.

@context에 대해 다음 규칙이 Thing Description 인스턴스에 대해 정의된다:

• @context 이름-값 쌍은 문서를 TD 1.1로 식별하여 Consumers가 새로 도입된 terms를 사용할 수 있도록 하기 위해 anyURI https://www.w3.org/2022/wot/td/v1.1를 포함해야 MUST 한다.
• TD 1.0 consumers가 있을 가능성이 있는 경우, anyURI https://www.w3.org/2019/wot/td/v1가 첫 번째 항목이어야 MUST 하며, https://www.w3.org/2022/wot/td/v1.1는 두 번째 항목이어야 MUST 한다.
• TD 1.1 consumers는 W3C WoT Thing Description 1.0 [wot-thing-description10] 명세를 만족하는 TD를 수용해야 MUST 한다.
• @context가 Array인 경우, anyURI https://www.w3.org/2022/wot/td/v1.1 뒤에는 임의의 순서로 anyURI 타입 또는 Map 타입의 요소가 올 수 MAY 있지만, @context Array 안의 모든 이름-값 쌍을 포함하는 하나의 Map만 포함하는 것이 RECOMMENDED된다.
• @context Array에 포함된 Maps는 이름-값 쌍을 포함할 수 MAY 있으며, 이때 값은 anyURI 타입의 네임스페이스 식별자이고 이름은 해당 네임스페이스를 나타내는 Term 또는 접두사이다.
• @context Array에 포함된 하나의 Map은 Thing Description의 기본 언어를 정의하는 이름-값 쌍을 포함해야 SHOULD 하며, 여기서 이름은 Term @language이고 값은 [BCP47]에서 정의한 올바른 형식의 언어 태그이다 (예: en, de-AT, gsw-CH, zh-Hans, zh-Hant-HK, sl-nedis).

Thing Description과 Thing Model 인스턴스의 사람이 읽을 수 있는 모든 텍스트의 기본 방향을 결정하기 위해, 이 명세는 기본 방향 메타데이터를 연결하는 내장 메커니즘이 없을 때 [STRING-META] 가이드라인의 문자열별 방향 정보를 따를 것을 권장한다.

TD Processors는 양방향 텍스트를 처리할 때 특정 특수 사례를 인식해야 한다. TD Processors는 특히 주변 텍스트에 삽입할 때(예: Web 사용자 인터페이스) 사용자에게 문자열을 표시할 때 bidi isolation을 사용하도록 주의해야 SHOULD 한다. 혼합 방향 텍스트는 언어가 올바르게 식별된 경우에도 어떤 언어에서든 발생할 수 있다.

TD producers는 단순한 사용자 에이전트가 성공적으로 표시할 수 있는 방식으로 혼합 방향 문자열을 제공하려고 시도해야 SHOULD 한다. 예를 들어, RTL 문자열이 LTR 런(예: 숫자 또는 라틴 문자로 된 브랜드나 상표명)으로 시작하는 경우, 문자열 시작 부분에 RLM 문자를 포함하거나 반대 방향 런을 bidi controls로 감싸면 올바른 표시를 도울 수 있다.

Strings on the Web: Language and Direction Metadata [string-meta]는 양방향 텍스트를 사용할 때의 여러 함정을 설명하고 지침을 제공한다.

properties, actions, 그리고 events Maps에서 명시적으로 제공되는 Interaction Affordance 외에도, Thing은 선택적 forms Array 안의 Form 인스턴스로 표시되는 meta-interactions도 제공할 수 있다. Thing 인스턴스의 forms Array가 Form 인스턴스를 포함하는 경우, 이는 op 멤버를 포함해야 MUST 하며, 이름 op에 할당된 문자열 값은 직접 또는 Array 안에서 다음 operation types 중 하나여야 MUST 한다: readallproperties, writeallproperties, readmultipleproperties, writemultipleproperties, observeallproperties, unobserveallproperties, queryallactions, subscribeallevents, 또는 unsubscribeallevents. (Thing 인스턴스에서 form을 사용하는 예는 예를 참조하라.)

각 property meta-interaction의 데이터 스키마는 각 PropertyAffordance 인스턴스의 데이터 스키마를 단일 ObjectSchema 인스턴스 안에 결합하여 구성되며, 여기서 ObjectSchema 인스턴스의 properties Map은 대응하는 PropertyAffordances 인스턴스의 이름으로 식별되는 각 PropertyAffordances의 데이터 스키마를 포함한다.

달리 지정되지 않는 한(예: TD Context Extension을 통해), readmultipleproperties 작업의 요청 데이터는 의도한 PropertyAffordances 인스턴스 이름을 포함하는 Array이며, Form 인스턴스가 지정한 콘텐츠 타입으로 직렬화된다.

가능한 선택지를 Consumers에게 보여 주어, Consumers가 Thing과 상호작용할 수 있는 방법을 제안하는 Thing의 메타데이터. 잠재적인 affordance에는 여러 유형이 있지만, W3C WoT는 세 가지 유형의 Interaction Affordances를 정의한다: Properties, Actions, Events.

InteractionAffordance 클래스는 다음 하위 클래스를 가진다:

• PropertyAffordance
• ActionAffordance
• EventAffordance

Thing의 상태를 노출하는 Interaction Affordance. 이 상태는 검색(읽기)되거나 업데이트(쓰기)될 수 있다. Things는 변경 후 새 상태를 push함으로써 Properties를 관찰 가능하게 만들 수도 있다.

PropertyAffordance는 InteractionAffordance Class와 DataSchema Class의 Subclass이다. PropertyAffordance 인스턴스 안에 Form 인스턴스가 있는 경우, op에 할당된 값은 readproperty, writeproperty, observeproperty, unobserveproperty 중 하나이거나 이러한 terms의 조합을 포함하는 Array여야 MUST 한다.

상태를 조작하거나(예: 램프 켜기/끄기 토글) Thing에서 프로세스를 트리거하는(예: 시간이 지남에 따라 램프를 어둡게 하기) Thing의 함수를 호출할 수 있게 하는 Interaction Affordance.

ActionAffordance는 InteractionAffordance Class의 Subclass이다. ActionAffordance 인스턴스 안에 Form 인스턴스가 있는 경우, op에 할당된 값은 invokeaction, queryaction, cancelaction 중 하나이거나 이러한 terms의 조합을 포함하는 Array여야 MUST 한다.

이벤트 데이터를 Consumers에게 비동기적으로 push하는 이벤트 소스를 설명하는 Interaction Affordance (예: 과열 경고).

EventAffordance는 InteractionAffordance Class의 Subclass이다. EventAffordance 인스턴스 안에 Form 인스턴스가 있는 경우, op에 할당된 값은 subscribeevent, unsubscribeevent 중 하나이거나 Array 안에 두 terms 모두여야 MUST 한다.

EventAffordances는 Thing 자체가 관심 있는 Consumers에게 상태 변경을 알린다는 점에서 observable PropertyAffordances와 유사하다. 그러나 EventAffordances의 주요 차이점은 관련 리소스의 모든 변경이 이벤트 메시지를 발생시킬 필요는 없다는 것이다. 예를 들어 숫자 값의 임계 임계값이 있을 수 있다. 또한 EventAffordances는 subscription, dataResponse, 그리고 cancellation DataSchema 정의를 통해 더 복잡한 구독 및 구독 해지 메커니즘을 허용한다. 하지만 모든 프로토콜이 이러한 더 고급 메커니즘을 지원하는 것은 아닐 수 있으므로, 일부 시나리오에서는 events가 observable PropertyAffordances와 매우 유사할 수 있다. 이러한 경우 Affordance를 모델링하기 위해 Property와 Event 중 무엇을 선택할지는 기반 리소스의 의미론을 기반으로 결정해야 한다. 예를 들어 affordance의 상태가 Consumer에 의해 읽히거나 쓰여야 한다면, Property가 가장 적절한 선택일 가능성이 높다.

TD 문서에 대한 버전 정보를 제공하는 Thing의 메타데이터. 필요한 경우 펌웨어 및 하드웨어 버전과 같은 추가 버전 정보 (TD 네임스페이스 외부의 term 정의)는 TD Context Extension 메커니즘을 통해 확장할 수 있다.

VersionInfo Class의 instances 및 model 안의 값은 점으로 구분된 세 숫자의 시퀀스가 각각 주 버전, 부 버전, 패치 버전을 나타내는 semantic versioning 패턴을 따르는 것이 권장된다. 자세한 내용은 [SEMVER]를 참조하라.

[BCP47]에 설명된 언어 태그로 식별되는 여러 언어의 사람이 읽을 수 있는 텍스트 집합을 제공하는 Map. Thing Description 인스턴스에서 이 컨테이너를 사용하는 예는 6.3.2 사람이 읽을 수 있는 메타데이터를 참조하라.

MultiLanguage Map의 각 이름은 [BCP47]에서 정의한 언어 태그여야 MUST 한다. MultiLanguage Map의 각 값은 string 타입이어야 MUST 한다.

사용되는 데이터 형식을 설명하는 메타데이터. 검증에 사용할 수 있다.

DataSchema 클래스는 다음 하위 클래스를 가진다:

• ArraySchema
• BooleanSchema
• NumberSchema
• IntegerSchema
• ObjectSchema
• StringSchema
• NullSchema

format 문자열 값은 알려진 고정 값 집합과 [JSON-SCHEMA]에 정의된 해당 format 규칙(특히 섹션 7.3 Defined Formats)에서 알려져 있다. Servients는 그에 따라 추가 검증을 수행하기 위해 format 값을 사용할 수 MAY 있다. 알려진 값 집합에서 찾을 수 없는 값이 format에 할당된 경우, 그러한 검증은 성공해야 SHOULD 한다.

Array 타입의 데이터를 설명하는 메타데이터. 이 Subclass는 DataSchema 인스턴스에서 type에 할당된 array 값으로 표시된다.

boolean 타입의 데이터를 설명하는 메타데이터. 이 Subclass는 DataSchema 인스턴스에서 type에 할당된 boolean 값으로 표시된다.

number 타입의 데이터를 설명하는 메타데이터. 이 Subclass는 DataSchema 인스턴스에서 type에 할당된 number 값으로 표시된다.

integer 타입의 데이터를 설명하는 메타데이터. 이 Subclass는 DataSchema 인스턴스에서 type에 할당된 integer 값으로 표시된다.

Object 타입의 데이터를 설명하는 메타데이터. 이 Subclass는 DataSchema 인스턴스에서 type에 할당된 object 값으로 표시된다.

string 타입의 데이터를 설명하는 메타데이터. 이 Subclass는 DataSchema 인스턴스에서 type에 할당된 string 값으로 표시된다.

null 타입의 데이터를 설명하는 메타데이터. 이 subclass는 DataSchema 인스턴스에서 type에 할당된 null 값으로 표시된다. 이 Subclass는 오직 하나의 허용 가능한 값, 즉 null만을 설명한다. null이 값의 부재를 의미하지 않는다는 점에 유의하는 것이 중요하다. 이는 JavaScript의 null, Python의 None, Java의 null, Ruby 프로그래밍 언어의 nil과 유사하다. 이는 oneOf 선언의 일부로 사용할 수 있으며, 데이터가 null일 수도 있음을 나타내는 데 사용된다.

보안 메커니즘의 구성을 설명하는 메타데이터. 이름 scheme에 할당된 값은 Thing Description에 포함된 Vocabulary 안에서 정의되어야 MUST 하며, 이는 § 5. TD Information Model에서 정의된 표준 Vocabulary 안이거나 TD Context Extension 안이어야 한다.

모든 보안 스킴에 대해, 접근을 직접 제공하는 키, 비밀번호 또는 기타 민감한 정보는 TD에 저장되어서는 MUST NOT 안 되며, 대신 다른 메커니즘을 통해 대역 외에서 공유되고 저장되어야 한다. TD의 목적은 Consumer가 이미 권한을 가진 경우에만 Thing에 접근하는 방법을 설명하는 것이며, 그 권한을 부여하는 데 사용되도록 의도된 것이 아니다.

TD에서 사용되는 각 보안 스킴 객체는 접근이 허용되기 전에 충족되어야 하는 요구사항 집합을 정의한다. 우리는 모든 요구사항이 충족될 때 보안 스킴이 만족된다고 말한다. 어떤 경우에는 접근이 허용되기 전에 여러 보안 스킴의 요구사항이 충족되어야 할 수도 있다.

보안 스킴은 일반적으로 비밀번호나 키와 같은 추가 인증 매개변수를 요구할 수 있다. 이 정보의 위치는 이름 in과 연결된 값으로 표시되며, 종종 name과 연결된 값과 함께 사용된다. in과 연결된 값은 다음 값 중 하나를 취할 수 있다:

header:

매개변수는 프로토콜이 제공하는 헤더에 주어지며, 헤더의 이름은 name 값으로 제공된다.

query:

매개변수는 URI에 쿼리 매개변수로 추가되며, 쿼리 매개변수의 이름은 name으로 제공된다.

body:

매개변수는 요청 페이로드의 본문에 제공되며, 사용되는 데이터 스키마 요소는 name으로 제공된다. body 보안 정보 위치의 문맥에서 사용될 때, name의 값은 그것이 사용되는 각 상호작용에 대한 입력 DataSchema의 루트에 상대적인 JSON pointer [RFC6901] 형식이어야 MUST 한다. 이 값은 fragment identifier가 아니며 TD의 루트에 상대적인 것이 아니라 보안 스킴이 바인딩되는 데이터 스키마에 상대적이므로, #로 시작해서는 안 된다. 이는 “순수한” JSON pointer이다. 이 값은 fragment identifier가 아니므로 특수 문자를 URL 인코딩할 필요도 없다. 대상 요소는 참조된 object 또는 array schema의 지정된 위치에 이미 존재할 수도 있고 존재하지 않을 수도 있다(따라서 이 메커니즘은 simple types에는 적용되지 않는다). 존재하지 않으면 삽입된다. 이는 모든 상호작용의 데이터 스키마에서 정의를 중복해야 하는 일을 피하게 한다. body locator에 표시된 JSON pointer가 나타내는 데이터 스키마 요소가 표시된 스키마에 아직 존재하지 않는 경우, pointer가 나타내는 위치에 해당 요소를 삽입할 수 있어야 MUST 한다. body locator에서 사용되는 JSON pointer는 기존 배열의 마지막 요소 뒤에 요소를 삽입해야 할 때 존재하지 않는 배열 요소를 나타내기 위해 "-" 문자를 사용할 수 MAY 있다. body 보안 정보 위치가 참조하거나 생성하는 요소는 필수이며 "string" 타입이어야 MUST 한다. name이 주어지지 않으면 전체 본문이 보안 매개변수로 사용되는 것으로 간주된다.

cookie:

매개변수는 name 값으로 식별되는 쿠키에 저장된다.

uri:

매개변수는 URI 자체에 포함되며, name 값으로 정의된 URI 템플릿 변수를 사용하여 관련 상호작용에서 인코딩된다. 이는 query 메커니즘보다 더 일반적이지만 더 복잡하다. 보안 스킴에서 이름 in에 대한 값으로 uri는 query가 적용되지 않는 경우에만 지정되어야 SHOULD 한다. in의 값으로 uri를 사용하는 보안 스킴이 있는 상호작용에서 제공되는 URI는 정의된 변수를 포함하는 URI 템플릿이어야 MUST 한다.

auto:

위치는 프로토콜의 일부로 결정되거나 협상된다. SecurityScheme의 in 필드에 auto 값이 설정된 경우, name 필드는 설정되지 않아야 SHOULD NOT 한다. 이 경우 SecurityScheme의 적용은 주어진 프로토콜에 대한 각각의 명세를 따른다(예: HTTP와 함께 BasicSecurityScheme을 사용할 때 [RFC8288]).

보안 스킴에 여러 매개변수가 필요한 경우, 각 매개변수에 대해 보안 스킴 정의를 반복하고 combo 보안 스킴과 allOf를 사용하여 결합한다. 어떤 경우에는 매개변수가 실제로 비밀이 아닐 수 있지만, 사용자가 개인정보 보호를 돕기 위해 이를 TD에서 제외하고자 할 수 있다. 예를 들어 일부 보안 메커니즘은 클라이언트 식별자와 비밀 키를 모두 요구한다. 이론적으로 클라이언트 식별자는 공개되어 있지만 업데이트하기 어려울 수 있고 추적 위험을 야기할 수 있다. 이러한 경우 TD에 나타나지 않도록 추가 보안 매개변수로 제공할 수 있다.

SecurityScheme에서 선언된 URI 변수의 이름은 TD에서 선언된 다른 모든 URI 변수와 구별되어야 MUST 한다.

SecurityScheme 클래스는 다음 하위 클래스를 가진다:

• NoSecurityScheme
• AutoSecurityScheme
• ComboSecurityScheme
• BasicSecurityScheme
• DigestSecurityScheme
• APIKeySecurityScheme
• BearerSecurityScheme
• PSKSecurityScheme
• OAuth2SecurityScheme

Vocabulary Term nosec로 식별되는 보안 구성 (즉, "scheme": "nosec")으로, 리소스에 접근하기 위해 인증이나 기타 메커니즘이 필요하지 않음을 나타낸다.

term auto로 식별되는 자동 인증 보안 구성 (즉, "scheme": "auto"). 이 스킴은 보안 매개변수가 런타임에 기반 프로토콜에 의해 협상되며, 주어진 프로토콜에 대한 각각의 명세를 따른다는 것을 나타낸다 (예: HTTP를 사용할 때 Basic Authentication에 대해 [RFC8288]).

Vocabulary Term combo로 식별되는 다른 보안 스킴의 조합 (즉, "scheme": "combo"). 이 스킴의 요소들은 securityDefinitions에 정의된 다른 이름 있는 스킴들, 다른 ComboSecurityScheme 정의를 포함하여, 새로운 스킴 정의를 만들기 위해 결합되는 다양한 방식을 정의한다. oneOf 또는 allOf vocabulary terms 중 정확히 하나가 포함되어야 MUST 한다. 함께 사용할 수 있는 보안 스킴 정의만 allOf와 결합할 수 있다. 예를 들어 하나가 프록시에 적용되고 다른 하나가 endpoint에 적용되는 경우가 아니면, 일반적으로 서로 다른 OAuth 2.0 flows를 allOf로 함께 결합하는 것은 불가능하다. 여러 이름 있는 보안 스킴 정의가 security 필드에 나열된 경우, allOf 조합과 동일한 의미론이 적용된다는 점에 유의하라(허용 가능한 조합에 대한 동일한 제한도 적용된다). oneOf 조합은 그 외에는 동일한 forms에서 서로 다른 보안 스킴을 사용하는 것과 동등하다. 이런 의미에서 oneOf 스킴은 필수적인 기능은 아니지만, 그러한 경우 중복을 피할 수 있게 한다.

암호화되지 않은 사용자 이름과 비밀번호를 사용하는, Vocabulary Term basic (즉, "scheme": "basic")으로 식별되는 Basic Authentication [RFC7617] 보안 구성.

Vocabulary Term digest (즉, "scheme": "digest")로 식별되는 Digest Access Authentication [RFC7616] 보안 구성. 이 스킴은 basic authentication과 유사하지만 man-in-the-middle attacks를 피하기 위한 추가 기능을 가진다.

Vocabulary Term apikey (즉, "scheme": "apikey")로 식별되는 API key authentication 보안 구성. 이 스킴은 access token이 불투명한 경우, 예를 들어 클라우드 서비스 제공자가 알 수 없거나 독점적인 형식의 키를 제공하는 경우 사용된다. 이 경우 키는 표준 token 형식을 사용하지 않을 수 있다. 이 스킴은 서비스 제공자가 제공한 키가 "in" 필드가 나타내는 메커니즘을 사용하여 서비스 요청의 일부로 제공되어야 함을 나타낸다.

bearer tokens가 OAuth2와 독립적으로 사용되는 상황을 위한, Vocabulary Term bearer (즉, "scheme": "bearer")로 식별되는 Bearer Token [RFC6750] 보안 구성. oauth2 스킴이 지정된 경우, 이것이 암시되므로 일반적으로 이 스킴을 함께 지정할 필요는 없다. format에 대해, 값 jwt는 [RFC7519] 준수를 나타내고, jws는 [RFC7797] 준수를 나타내며, cwt는 [RFC8392] 준수를 나타내고, jwe는 [RFC7516] 준수를 나타내며, alg의 값은 이러한 표준과 일관되게 해석된다. bearer tokens에 대한 다른 형식과 알고리즘은 vocabulary extensions에서 지정될 수 MAY 있다.

Vocabulary Term psk (즉, "scheme": "psk")로 식별되는 pre-shared key authentication 보안 구성. 이는 TLS-PSK [RFC4279]와 같은 pre-shared keys에 표준이 사용되며, 키에 사용되는 ciphersuite가 프로토콜 협상 중에 설정된다는 것을 식별하기 위한 것이다.

[RFC6749] 및 [RFC8252]를 준수하는 시스템을 위한 OAuth 2.0 authentication 보안 구성으로, Vocabulary Term oauth2 (즉, "scheme": "oauth2")로 식별된다.

code flow의 경우 authorization 및 token vocabulary terms가 모두 포함되어야 MUST 한다. client flow의 경우 token vocabulary term이 포함되어야 MUST 한다. client flow의 경우 authorization vocabulary term은 포함되어서는 MUST NOT 안 된다. 각 flow의 필수 요소는 다음 표에 요약되어 있다:

link는 "link context가 link target에 relation type 리소스를 가진다"라는 형식의 문장으로 볼 수 있으며, 선택적 target attributes는 리소스를 추가로 설명할 수 있다.

Link relations는 다른 Things와의 관계(예: Switch Thing이 Lamp Thing을 제어함), 특정 종류의 Thing Models와의 관계 (예: Thing Description이 특정 Thing Model의 인스턴스임), 또는 추가 문서 정보(예: Thing의 장치 설명서)를 설명하는 데 사용할 수 있다. 기존의 확립된 IANA의 Link Relation 정의를 재사용하는 것이 권장된다.

다음에서는 WoT Thing Description 또는 Thing Model 인스턴스 안에서 사용할 것을 권장하는 best practice relation type 표를 소개한다.

form은 " form context에서 operation type 작업을 수행하려면, submission target에 request method 요청을 하라"라는 문장으로 볼 수 있으며, 선택적 form fields는 필요한 요청을 추가로 설명할 수 있다. Thing Descriptions에서 form context는 Properties, Actions, Events와 같은 주변 Object이거나 meta-interactions의 경우 Thing 자체이다.

contentCoding property에 가능한 값은 예를 들어 IANA HTTP content coding registry에서 찾을 수 있다.

form의 가능한 operation types 목록은 고정되어 있다. 이 명세의 현재 버전 기준으로, [wot-architecture11]에 설명된 WoT interaction model을 구현하는 데 필요한 잘 알려진 types만 포함한다. 표준의 향후 버전은 이 목록을 확장할 수 있지만, operations types는 아래 표의 값으로 제한되어야 MUST 한다.

WoT producer의 Thing Description은 Consumer가 지원할 수 있는, 예를 들어 서로 다른 프로토콜 및/또는 콘텐츠 타입 선언을 가진 여러 forms entries를 가질 수 있다. 이 경우 Consumer는 자신에게 작동하는(예: 프로토콜과 콘텐츠 타입이 지원되는) 어떤 form entry든 선택할 수 있다. 하나의 form이 선택되면, Consumer는 WoT producer와의 모든 새로운 상호작용에서 가능한 한 오랫동안 그것을 계속 사용할 것으로 기대된다.

primary response에 대한 예상 response message를 설명하는 통신 메타데이터.

additional responses에 대한 예상 response message를 설명하는 통신 메타데이터.

좀 더 복잡한 예를 들면, 하나를 제외한 모든 Interaction Affordances가 basic authentication을 요구하고, 그 하나에는 authentication이 필요하지 않은 Thing이 있다고 가정하자. status Property와 toggle Action의 경우 basic authentication이 필요하며 Thing level에서 정의된다. 그러나 overheating Event의 경우 authentication이 필요하지 않으므로, 보안 구성이 form level에서 재정의된다.

{
    // ...
    "securityDefinitions": {
        "basic_sc": {"scheme": "basic"},
        "nosec_sc": {"scheme": "nosec"}
    },
    "security": "basic_sc",
    // ...
    "properties": {
        "status": {
            // ...
            "forms": [{
                "href": "https://mylamp.example.com/status"
            }]
        }
    },
    "actions": {
        "toggle": {
            // ...
            "forms": [{
                "href": "https://mylamp.example.com/toggle"
            }]
        }
    },
    "events": {
        "overheating": {
            // ...
            "forms": [{
                "href": "https://mylamp.example.com/oh",
                "security": "nosec_sc"
            }]
        }
    }
}

TD는 보안 스킴의 조합도 지정할 수 있다. 아래는 proxy에서 digest authentication을 사용하고, Thing에서 bearer token authentication을 결합한 TD 스니펫이다. digest 스킴에서 in의 Default Value (즉, header)는 생략되지만 여전히 적용된다. 성공적으로 상호작용하려면 username/password 및 tokens와 같은 해당 비공개 보안 구성이 Consumer에서 구성되어야 한다는 점에 유의하라. 여러 보안 정의를 활성화할 때, security 멤버는 배열이 된다.

{
    // ...
    "securityDefinitions": {
        "proxy_sc": {
            "scheme": "digest",
            "proxy": "https://portal.example.com/"
        },
        "bearer_sc": {
            "scheme": "bearer",
            "in": "header",
            "format": "jwt",
            "alg": "ES256",
            "authorization": "https://servient.example.com:8443/"
        }
    },
    "security": ["proxy_sc", "bearer_sc"],
    // ...
}

그러나 security 요소에서 여러 요소를 가진 배열을 사용하여 보안 스킴을 결합하는 것은 이제 deprecated되었으며, 대신 ComboSecurityScheme을 사용해야 SHOULD 한다. 다음 예는 위 예와 정확히 동일하며, 이를 보여 준다:

{
    // ...
    "securityDefinitions": {
        "proxy_sc": {
            "scheme": "digest",
            "proxy": "https://portal.example.com/"
        },
        "bearer_sc": {
            "scheme": "bearer",
            "in": "header",
            "format": "jwt",
            "alg": "ES256",
            "authorization": "https://servient.example.com:8443/"
        },
        "combo_sc": {
            "scheme": "combo",
            "allOf": ["proxy_sc", "bearer_sc"]
        }
    },
    "security": "combo_sc",
    // ...
}

보안 구성은 같은 Interaction Affordance 안의 서로 다른 forms에 대해서도 지정할 수 있다. 이는 예를 들어 HTTP와 CoAP [RFC7252]처럼 서로 다른 보안 메커니즘을 지원하는 여러 프로토콜을 지원하는 장치에 필요할 수 있다. 대체 authentication 메커니즘이 허용될 때도 유용하다. 다음은 Property affordance를 활성화하는 세 가지 가능한 방법, 즉 basic authentication이 있는 HTTPS, digest authentication, bearer token authentication을 보여 주는 TD 스니펫이다. 다시 말해, 여러 forms 안에서 서로 다른 보안 구성을 사용하는 것은 보안 메커니즘을 "OR" 방식으로 결합하는 방법을 제공한다. 반대로 같은 security 멤버 안에 여러 보안 구성을 넣으면, 그 경우 Interaction Affordance의 활성화를 허용하기 위해 그것들이 모두 만족되어야 하므로 "AND" 방식으로 결합된다. Thing level에서 하나의 (기본) 구성을 활성화하는 것은 여전히 필수임에 유의하라.

{
    // ...
    "securityDefinitions": {
        "basic_sc": { "scheme": "basic" },
        "digest_sc": { "scheme": "digest" },
        "bearer_sc": { "scheme": "bearer" }
    },
    "security": "basic_sc",
    // ...
    "properties": {
        "status": {
            // ...
            "forms": [{
                "href": "https://mylamp.example.com/status"
            }, {
                "href": "https://mylamp.example.com/status",
                "security": "digest_sc"
            }, {
                "href": "https://mylamp.example.com/status",
                "security": "bearer_sc"
            }]
        }
    },
    // ...
}

이 경우 중복을 피하기 위해, 예를 들어 form 요소의 세부 정보를 반복하는 대신, oneOf가 있는 ComboSecurityScheme을 사용할 수 있다.

{
    // ...
    "securityDefinitions": {
        "basic_sc": { "scheme": "basic" },
        "digest_sc": { "scheme": "digest" },
        "bearer_sc": { "scheme": "bearer" },
        "combo_sc": {
            "scheme": "combo",
            "oneOf": [ "basic_sc", "digest_sc", "bearer_sc" ]
        }
    },
    "security": "combo_sc",
    // ...
    "properties": {
        "status": {
            // ...
            "forms": [{
                "href": "https://mylamp.example.com/status"
            }]
        }
    },
    // ...
}

또 다른 더 복잡한 예로, OAuth 2.0은 scopes를 사용한다. 이는 tokens 안에 나타날 수 있는 식별자이며, 해당 리소스 (또는 W3C WoT의 경우 Interaction Affordance)에 대한 접근을 허용하려면 리소스의 대응 식별자와 일치해야 한다. 예를 들어 다음에서 status Property는 scope limited를 포함하는 bearer tokens를 사용하는 Consumers가 읽을 수 있지만, configure Action은 special scope를 포함하는 token으로만 호출될 수 있다. Scopes는 roles와 동일하지 않지만 종종 관련된다. 예를 들어 아마도 administrative role에 있는 사람만 "special" 상호작용을 수행할 권한을 가질 수 있다. Tokens는 둘 이상의 scope를 가질 수 있으며, 전용 web services가 사용자에게 발급한다. 이 예에서 관리자는 limited와 special scope를 모두 가진 tokens를 발급받을 수 있고, 일반 사용자는 limited scope를 가진 tokens를 제공받을 수 있다.

{
    // ...
    "securityDefinitions": {
        "oauth2_sc": {
            "scheme": "oauth2",
            "flow": "client",
            "token": "https://example.com/token",
            "scopes": ["limited", "special"]
        }
    },
    "security": "oauth2_sc",
    // ...
    "properties": {
        "status": {
            // ...
            "forms": [{
                "href": "https://scopes.example.com/status",
                "scopes": ["limited"]
            }]
        }
    },
    "actions": {
        "configure": {
            // ...
            "forms": [{
                "href": "https://scopes.example.com/configure",
                "scopes": ["special"]
            }]
        }
    },
    // ...
}

Thing은 Consumer가 Thing과 상호작용하기 위해 API key를 요구하게 되는 onboarding 프로세스를 요구할 수 있다. 이 API key는 API key 스킴이 지정하는 여러 방식으로 Thing에 대한 요청에 포함될 수 있다. 아래는 Consumer가 HTTPS 요청을 보낼 때 URI 안에서 API key를 대체해야 하는 URI template으로 API key를 사용할 수 있는 방법의 예이다.

{
    // ...
    "securityDefinitions": {
        "apikey_key": {
            "scheme": "apikey",
            "in": "uri",
            "name": "adminKey"
        }
    },
    "security": "apikey_key",
    "properties": {
        "status": {
            // ...
            "forms": [{
                "href": "https://example.com/{adminKey}/status",
                // ...
            }]
        }
    },
    // ...
}

위에 표시된 URI templates 예에 더해 ComboSecurityScheme 사용의 또 다른 예를 들면, client ID와 cloud service provider가 제공하는 "secret" key가 모두 URL 안에 삽입되어야 하는 보안 스킴이 있다고 가정하자. 기술적으로는 key만 실제로 secret이며 out-of-band로 처리되어야 하고, secret이 아닌 client ID는 TD에 삽입될 수도 있다. 그러나 client ID를 쉽게 교체할 수 없다면 개인정보 보호를 강화하기 위해 TD에 삽입하는 것을 피하고 싶을 수 있다. 이 경우 in 위치 지정자에 대해 모두 uri 값을 사용하는 APIKeySecurityScheme 두 인스턴스를 결합하여 두 개의 URI 변수를 선언할 수 있다. 그런 다음 이 변수들은 보안 스킴이 활성인 Form의 href에서 사용될 수 있다(사실 반드시 사용되어야 한다). 예는 다음과 같다:

{
    // ...
    "securityDefinitions": {
        "apikey_key": {
            "scheme": "apikey",
            "in": "uri",
            "name": "secKey"
        },
        "apikey_id": {
            "scheme": "apikey",
            "in": "uri",
            "name": "secClientID"
        },
        "apikey_combo": {
            "scheme": "combo",
            "allOf": ["apikey_key","apikey_id"]
        }
    },
    "security": "apikey_combo",
    // ...
    "properties": {
        "status": {
            // ...
            "forms": [{
                "href": "https://example.com/{secClientID}/status/{secKey}",
                // ...
            }]
        }
    },
    // ...
}

이 예에는 표시되어 있지 않지만, uriVariables를 사용하여 추가 URI template 변수를 선언하고 같은 URI template에 포함하는 것은 적법하다. 다만 이름은 보안 스킴에서 선언된 이름과 충돌할 수 없다. 위 예에서처럼 보안 스킴에서 선언된 URI 변수에 특정 접두사를 사용하면 이름 충돌을 피하기가 더 쉬워질 수 있다.

본문 안의 API Key: 일부 시스템에서는 보안 매개변수가 payload와 함께 포함될 수도 있다. 예를 들어 어떤 시스템이 모든 payload가 auth라는 이름의 멤버를 포함하는 JSON 객체여야 하며, 그 값은 access key를 포함하는 key라는 멤버를 가진 객체여야 한다고 요구한다고 가정하자. 그러나 상호작용에 따라 JSON 객체의 다른 요소들은 달라질 수 있다. 이러한 상황은 body 보안 정보 위치를 사용하여 처리할 수 있다. 이 위치의 경우 name 매개변수는 실제로, 바인딩되는 각 상호작용에 대한 DataSchema의 루트에 상대적으로 평가되는 JSON pointer이므로, 다른 측면에서 달라지는 payload와 함께 사용할 수 있다는 점에 유의하라. 예로, 밝기와 색상을 설정하는 property와 켜기 및 끄기를 위한 두 개의 별도 actions가 있는 조명이 있다고 하자. 이러한 actions의 JSON payload가 서로 다르더라도 /auth/key 요소는 같은 상대 위치에 나타나므로 단일 JSON pointer를 사용할 수 있다. 참고: 보안 key가 서로 일관되지 않은 다른 위치에 나타나는 경우, 여러 보안 스킴 정의를 사용해야 한다.

{
    // ...
    "securityDefinitions": {
        "apikey_body": {
            "scheme": "apikey",
            "in": "body",
            "name": "/auth/key"
        }
    },
    "security": "apikey_body",
    // ...
    "properties": {
        "color": {
            // ...
            "type": "object",
            "properties": {
                "brightness": {
                    "type": "number",
                    // ...
                },
                "rgb": {
                    "type": "array",
                    // ...
                },
                "auth": {
                    "type": "object",
                    "properties": {
                        "key": {
                           "type": "string"
                        }
                    },
                    "required": ["key"]
                }
            },
            "required": ["brightness", "rgb", "auth"],
            "forms": [{
                "href": "https://example.com/color",
                // ...
            }]
        }
    },
    "action": {
        "on": {
            // ...
            "input": {
                "auth": {
                    "type": "object",
                    "properties": {
                        "key": {
                           "type": "string"
                        }
                    },
                    "required": ["key"]
                }
            },
            "required": ["auth"],
            "forms": [{
                "href": "https://example.com/on",
                // ...
            }]
        },
        "off": {
            // ...
            "input": {
                "auth": {
                    "type": "object",
                    "properties": {
                        "key": {
                           "type": "string"
                        }
                    },
                    "required": ["key"]
                }
            },
            "required": ["auth"],
            "forms": [{
                "href": "https://example.com/off",
                // ...
            }]
        }
    },
    // ...
}

{
    // ...
    "securityDefinitions": {
        "apikey_body": {
            "scheme": "apikey",
            "in": "body",
            "name": "/auth/key"
        }
    },
    "security": "apikey_body",
    // ...
    "properties": {
        "color": {
            // ...
            "type": "object",
            "properties": {
                "brightness": {
                    "type": "number",
                    // ...
                },
                "rgb": {
                    "type": "array",
                    // ...
                }
            },
            "required": ["brightness", "rgb"],
            "forms": [{
                "href": "https://example.com/color",
                // ...
            }]
        }
    },
    "action": {
        "on": {
            // ...
            "required": ["auth"],
            "forms": [{
                "href": "https://example.com/on",
                // ...
            }]
        },
        "off": {
            // ...
            "forms": [{
                "href": "https://example.com/off",
                // ...
            }]
        }
    },
    // ...
}

href는 http://example.org/weather/?lat=35&lon=139의 lat 및 lon과 같은 동적 변수를 포함하는 URI를 담을 수도 있다. 이 경우 URI는 [RFC6570]에 정의된 template으로 정의될 수 있다: http://example.org/weather/{?lat,long}.

그러한 경우, URI Template 변수는 Thing level 또는 Interaction Affordance level에서 관련된(고유한) 변수 이름을 JSON 이름으로 사용하여 JSON 객체 기반 uriVariables 멤버에 수집되어야 MUST 한다.

Form의 인스턴스에서 uriVariables에 할당된 map의 각 값의 직렬화는 Class DataSchema에 의존해야 MUST 하며, 그 직렬화는 6.3.10 Data Schemas에서 정의된다.

query parameters를 위한 URI Template과 Interaction Affordance level의 uriVariables를 사용하는 TD 스니펫은 아래에 제공된다:

{
    "@context": ["https://www.w3.org/ns/wot-next/td", {
        "htv": "http://www.w3.org/2011/http#"
    }],
    // ...
    "properties": {
        "weather": {
            // ...
            "uriVariables": {
                "lat": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 90,
                    "description": "Latitude for the desired location in the world" },
                "long": {
                    "type": "number",
                    "minimum": -180,
                    "maximum": 180,
                    "description": "Longitude for the desired location in the world" }
            },
            "forms": [{
              "href": "http://example.org/weather/{?lat,long}",
              "htv:methodName": "GET"
            }]
        },
        // ...
    },
    // ...
}

또는 [RFC6570]에 정의된 것처럼, uriVariables는 href 구조를 대체하는 데 사용할 수 있다. 콜롬비아 보고타의 예보를 가져오기 위한 유효한 요청이 http://example.org/weather/bogota에 대한 HTTP GET 요청이 되는 TD 예가 아래에 제공된다:

{
    "@context": ["https://www.w3.org/ns/wot-next/td", {
        "htv": "http://www.w3.org/2011/http#"
    }],
    // ...
    "properties": {
        "weather": {
            // ...
            "uriVariables": {
                "city": {
                    "type": "string",
                    "description": "City name to find the weather information for"
                }
            },
            "forms": [{
                "href": "http://example.org/weather/{city}",
                "htv:methodName": "GET"
            }]
        },
        // ...
    },
    // ...
}

아래 두 예는 동일한 uriVariables 기능을 사용하면서 결합될 수도 있다. http://example.org/weather/bogota/?unit=Celsius에 대한 HTTP GET 요청은 다음과 같이 설명될 수 있다:

{
    "@context": ["https://www.w3.org/ns/wot-next/td", {
        "htv": "http://www.w3.org/2011/http#"
    }],
    // ...
    "properties": {
        "weather": {
            // ...
            "uriVariables": {
                "city": {
                    "type": "string",
                    "description": "City name to find the weather information for"
                },
                "unit": {
                    "type": "string",
                    "enum": ["fahrenheit_value","celsius_value"],
                    "description": "Desired unit for the temperature value"
                }
            },
            "forms": [{
                "href": "http://example.org/weather/{city}/{?unit}",
                "htv:methodName": "GET"
            }]
        },
        // ...
    },
    // ...
}

uriVariables는 주로 properties와 events를 위한 것이다. 기존 시스템을 개조할 때는 actions에 uriVariables를 사용해야 할 수도 있다. 일반적으로 새로운 WoT 기반 시스템을 설계할 때는 uriVariables 사용을 가능한 한 피하는 것이 권장된다.

contentType 멤버는 ; 문자로 구분된 attribute-value 쌍으로 media type parameters를 포함하는 media type [RFC2046]을 할당하는 데 사용된다. 예:

{
    // ...
    "contentType": "text/plain; charset=utf-8",
    // ...
}

일부 사용 사례에서 Interaction Affordance의 form metadata는 request를 설명할 뿐 아니라 예상 response에 대한 metadata도 제공한다. 예를 들어 Action takePhoto는 request payload에 JSON을 사용하여 카메라의 parameter settings(aperture priority, timer 등)를 제출하기 위한 input schema를 정의한다(즉, "contentType": "application/json"). 이 action의 output은 촬영된 사진이며, 예를 들어 JPEG 형식으로 제공된다. 이러한 경우 response 멤버는 response payload의 표현 형식을 나타내는 데 사용된다(예: "contentType": "image/jpeg"). 여기서는 content type이 표현 형식을 완전히 지정하므로 output schema가 필요하지 않다.

위에서 설명한 takePhoto Action을 기반으로 response 멤버가 있는 form 스니펫은 아래에 표시된다:

{
    // ...
    "actions": {
        "takePhoto": {
            // ...
            "forms": [{
                "op": "invokeaction",
                "href": "http://camera.example.com/api/snapshot",
                "contentType": "application/json",
                "response": {
                    "contentType": "image/jpeg"
                }
            }]
        }
    },
    // ...
}

responses가 payload를 포함할 것으로 예상되지 않으며 따라서 contentType도 없는 경우, 빈 response 객체를 사용하여 이 정보를 전달할 수 있다.

{
    // ...
    "actions": {
        "brewCoffee": {
            "description": "Invoking this action does not return a payload.",
            "input": {
              "type": "object",
              "properties": {
                "coffeeType": {
                  "enum": [
                    "espresso",
                    "americano",
                    "cappuccino",
                    "latte"
                  ]
                },
                "useOatMilk": {
                  "type": "boolean",
                  "default": false
                }
              },
              "required": [
                "coffeeType"
              ]
            },
            "forms": [{
                "op": "invokeaction",
                "href": "http://coffee-maker.example.com/brew-coffee",
                "contentType": "application/json",
                "response": {}
            }]
        }
    },
    // ...
}

어떤 경우에는 Interaction Affordance의 일부로 Thing으로부터 받은 message가 여러 이유로 달라질 수 있다. 그러한 이유에는 오류 사례나 유효한 response에 대한 대체 responses가 포함될 수 있다. 이러한 경우 additionalResponses terms를 사용하여 이 동작을 설명할 수 있다.

예를 들어 자동차 엔진을 켜는 Action Affordance는 악천후 조건이나 엔진에 유지보수가 필요한 경우 작동하지 않을 수 있다. 그러한 경우 Thing은 일반적으로 사용되지 않는 payload로 응답해야 한다.

Action Affordance 안에 additionalResponses 멤버가 있는 TD 스니펫은 아래에 표시된다. 첫 번째 요소는 output에 설명된 것과 다른 payload로 error response를 보낼 수 있는 위에서 언급한 경우를 보여 준다. 값이 false인 success는 이 payload가 오류 사례를 가리킨다는 사실을 나타내며, schema는 schemaDefinitions에서 사용된 payload 설명에 연결할 수 있게 한다. additionalResponses 안의 두 번째 요소도 error response를 설명하지만, 이번에는 response에 payload가 없다.

{
    // ...
    "schemaDefinitions": {
      "actionErrorPayload": {
        "type": "object",
        "properties": {
          "reason": {
            "type": "string",
            "enum": ["cold","hot","maintenance"]
          },
          "timeStamp": {
            "description": "UNIX time in numbers indicating when the error happened",
            "type": "number"
          }
        }
      }
    },
    // ...
    "actions": {
        "startEngine": {
            "output": {
              "type": "string"
            },
            "forms": [{
                "op": "invokeaction",
                "href": "http://mycar.example.com/api/engine",
                "contentType": "application/json",
                "additionalResponses": [
                  {
                    "success": false,
                    "contentType": "application/json",
                    "schema": "actionErrorPayload"
                  },
                  {
                    "success": false
                  },
                ]
            }]
        }
    },
    // ...
}

additionalResponses term은 오류가 아닌 경우에도 사용할 수 있다. 이 경우 success는 true로 설정되고, 다른 schema를 사용하여 payload를 설명할 수 있다.

어떤 경우에는 binary data가 text-based values 안에 삽입된다. 예를 들어 JSON string-based value가 base64로 인코딩된 이미지를 포함할 수 있다. contentMediaType 및 contentEncoding terms는 이러한 이름-값 쌍의 문맥과 인코딩 형식을 명확히 하는 데 사용할 수 있다. contentMediaType 및 contentEncoding의 사용 샘플은 아래에 표시된다:

{
    // ...
    "properties": {
        "image": {
                "description": "Provides latest image",
                "type": "string",
                "contentMediaType": "image/png",
                "contentEncoding": "base64",
                "forms": [{
                            "op": "readproperty",
                            "href": "coaps://mylamp.example.com/lastPicture",
                            "cov:methodName": "GET",
                            "contentType": "application/json"
                    }]
        }
    },
    // ...
}

forms가 top level에 존재할 때, 이는 Thing이 제공하는 meta interactions를 설명하는 데 사용할 수 있다. 예를 들어 operation types readallproperties 및 writeallproperties는 Consumers가 모든 properties를 한 번에 읽거나, 쓰거나, 관찰할 수 있게 하는 Thing과의 meta interactions를 위한 것이다. 아래 예에서 forms 멤버는 TD 루트 객체에 포함되어 있으며, Consumer는 submission target https://mylamp.example.com/properties를 사용하여 단일 프로토콜 transaction 안에서 Thing의 모든 Properties (즉, on, brightness, 그리고 timer)를 읽거나 쓸 수 있다.

{
    // ...
    "properties": {
        "on": {
            "type": "boolean",
            "forms": [...]
        },
        "brightness": {
            "type": "number",
            "forms": [...]
        },
        "timer": {
            "type": "integer",
            "forms": [...]
        }
    },
    // ...
    "forms": [{
        "op": "readallproperties",
        "href": "https://mylamp.example.com/properties",
        "contentType": "application/json",
        "htv:methodName": "GET"
    },
    {
        "op": "writeallproperties",
        "href": "https://mylamp.example.com/properties",
        "contentType": "application/json",
        "htv:methodName": "PUT"
    }]
}

Thing-level uriVariables는 여기서 operation에 추가 변수를 제공하거나 readmultipleproperties operation을 위한 Property Affordance 이름 목록을 지정하는 데 사용할 수 있다. 아래 예에서 properties의 unit은 그러한 변수를 통해 설정할 수 있으며, 원하는 properties 목록도 설정할 수 있다:

{
    // ...
    "properties": {
        "temperature": {
            "type": "number",
            "forms": [...]
        },
        "brightness": {
            "type": "number",
            "forms": [...]
        },
        "humidity": {
            "type": "integer",
            "forms": [...]
        }
    },
    "uriVariables": {
        "propertyNames": {
            "type": "string",
            "description": "Comma separated list of property names to select."
        },
        "unitSystem": {
            "type": "string",
            "enum": ["metric","imperial","uscustomary"],
            "description": "System of Measurement that will be used for the values"
        }
    },
    "forms": [{
        "op": "readallproperties",
        "href": "https://mything.example.com/properties{?unitSystem}",
        "contentType": "application/json",
        "htv:methodName": "GET"
    },
    {
        "op": "readmultipleproperties",
        "href": "https://mylamp.example.com/properties{?propertyNames,unitSystem}",
        "contentType": "application/json",
        "htv:methodName": "GET"
    }]
}

readmultipleproperties operation의 경우, URI https://mylamp.example.com/properties?propertyNames=humidity,temperature&unitSystem=metric에 대한 HTTP GET 요청 예는 metric System of Measurement와 함께 humidity 및 temperature Property Affordances의 값을 반환할 것이다.

operation type writeallproperties의 경우, Consumer가 모든 쓰기 가능한 (non readOnly) properties와 (새로) 할당된 값을 제공할 것으로 기대된다(예: payload 안에서). 마찬가지로 writemultipleproperties operation type의 경우, Consumer가 쓰기 가능한 (non readOnly) properties를 제공할 것으로 기대된다. Thing 측에서는, Thing이 readmultipleproperties 및 readallproperties operation types의 경우 읽을 수 있는 (non writeOnly) properties를 반환할 것으로 기대된다.