{"action":"created","issue":{"url":"https://api.github.com/repos/w3c/wot-thing-description/issues/307","repository_url":"https://api.github.com/repos/w3c/wot-thing-description","labels_url":"https://api.github.com/repos/w3c/wot-thing-description/issues/307/labels{/name}","comments_url":"https://api.github.com/repos/w3c/wot-thing-description/issues/307/comments","events_url":"https://api.github.com/repos/w3c/wot-thing-description/issues/307/events","html_url":"https://github.com/w3c/wot-thing-description/issues/307","id":384060067,"node_id":"MDU6SXNzdWUzODQwNjAwNjc=","number":307,"title":"Is the use of \"$ref\" and \"definitions\" allowed in TD ?","user":{"login":"ToruKawaguchi","id":17423222,"node_id":"MDQ6VXNlcjE3NDIzMjIy","avatar_url":"https://avatars1.githubusercontent.com/u/17423222?v=4","gravatar_id":"","url":"https://api.github.com/users/ToruKawaguchi","html_url":"https://github.com/ToruKawaguchi","followers_url":"https://api.github.com/users/ToruKawaguchi/followers","following_url":"https://api.github.com/users/ToruKawaguchi/following{/other_user}","gists_url":"https://api.github.com/users/ToruKawaguchi/gists{/gist_id}","starred_url":"https://api.github.com/users/ToruKawaguchi/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ToruKawaguchi/subscriptions","organizations_url":"https://api.github.com/users/ToruKawaguchi/orgs","repos_url":"https://api.github.com/users/ToruKawaguchi/repos","events_url":"https://api.github.com/users/ToruKawaguchi/events{/privacy}","received_events_url":"https://api.github.com/users/ToruKawaguchi/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":3,"created_at":"2018-11-25T08:45:34Z","updated_at":"2018-11-28T10:01:12Z","closed_at":null,"author_association":"CONTRIBUTOR","body":"Can anybody clarify whether it is possible to use \"$ref\" and \"definitions\" of JSON schema within a TD or not?\r\nThis is partly mentioned in <https://github.com/w3c/wot-thing-description/issues/151#issuecomment-407753552>, but was not clear to me what the conclusion is, so I am raising a new issue.\r\n\r\nSome existing REST based API requires not only property value itself but also some predefined fields in request/response body, such as id and type of the thing. It is following a design practice to make developers easy to understand what that data is for. In addition, HATEOAS approach requires links field in every response body. \r\n\r\nConsidering such use case, it is helpful if we could define a data schema separately from each property definition, from both TD readability and size point of view. \r\n\r\nIn addition, above use case is not suitable for automatic construction of data field by \"readall\" discussed in #151, so if we want to read all property at once we need to manually define a special property which includes all other properties. In such case, referencing the definition out from that property could reduce the size of TD. \r\n\r\nBelow is an experimental TD applying $ref and definitions according to above use case just for discussion:  \r\n\r\n```\r\n{\r\n\t\"id\": \"urn:dev:wot:com:example:servient:homeAirConditioner:1\",\r\n\t\"name\": \"MyHomeAirConditioner\",\r\n\t\"security\": [\r\n\t\t{\r\n\t\t\t\"scheme\": \"basic\"\r\n\t\t}\r\n\t],\r\n\t\"base\": \"https://www.example.com/devices/homeAirConditioner/1/\",\r\n\t\"properties\": {\r\n\t\t\"\": {\r\n\t\t\t\"title\": \"All properties\",\r\n\t\t\t\"description\": \"Retrieves or sets all properties at once\",\r\n\t\t\t\"type\": \"object\",\r\n\t\t\t\"properties\": {\r\n\t\t\t\t\"_id\": {\r\n\t\t\t\t\t\"$ref\": \"#/definitions/_id\"\r\n\t\t\t\t},\r\n\t\t\t\t\"_type\": {\r\n\t\t\t\t\t\"$ref\": \"#/definitions/_type\"\r\n\t\t\t\t},\r\n\t\t\t\t\"_properties\": {\r\n\t\t\t\t\t\"type\": \"object\", \r\n\t\t\t\t\t\"properties\": {\r\n\t\t\t\t\t\t\"operationStatus\": {\r\n\t\t\t\t\t\t\t\"$ref\": \"#/definitions/operationStatus\"\r\n\t\t\t\t\t\t},\r\n\t\t\t\t\t\t\"targetTemplatureCelcius\": {\r\n\t\t\t\t\t\t\t\"$ref\": \"#/definitions/targetTemplatureCelsius\"\r\n\t\t\t\t\t\t}\r\n\t\t\t\t\t}\r\n\t\t\t\t},\r\n\t\t\t\t\"links\": {\r\n\t\t\t\t\t\"$ref\": \"#/definitions/links\"\r\n\t\t\t\t}\r\n\t\t\t},\r\n\t\t\t\"forms\": [\r\n\t\t\t\t{\r\n\t\t\t\t\t\"href\": \"properties\"\r\n\t\t\t\t}\r\n\t\t\t]\r\n\t\t},\r\n\t\t\"operationStatus\": {\r\n\t\t\t\"type\": \"object\",\r\n\t\t\t\"properties\": {\r\n\t\t\t\t\"_id\": {\r\n\t\t\t\t\t\"$ref\": \"#/definitions/_id\"\r\n\t\t\t\t},\r\n\t\t\t\t\"_type\": {\r\n\t\t\t\t\t\"$ref\": \"#/definitions/_type\"\r\n\t\t\t\t},\r\n\t\t\t\t\"_properties\": {\r\n\t\t\t\t\t\"type\": \"object\", \r\n\t\t\t\t\t\"properties\": {\r\n\t\t\t\t\t\t\"operationStatus\": {\r\n\t\t\t\t\t\t\t\"$ref\": \"#/definitions/operationStatus\"\r\n\t\t\t\t\t\t}\r\n\t\t\t\t\t}\r\n\t\t\t\t},\r\n\t\t\t\t\"links\": {\r\n\t\t\t\t\t\"$ref\": \"#/definitions/links\"\r\n\t\t\t\t}\r\n\t\t\t},\r\n\t\t\t\"forms\": [\r\n\t\t\t\t{\r\n\t\t\t\t\t\"href\": \"properties/operationStatus\"\r\n\t\t\t\t}\r\n\t\t\t]\r\n\t\t},\r\n\t\t\"targetTemplatureCelsius\": {\r\n\t\t\t\"type\": \"object\",\r\n\t\t\t\"properties\": {\r\n\t\t\t\t\"_id\": {\r\n\t\t\t\t\t\"$ref\": \"#/definitions/_id\"\r\n\t\t\t\t},\r\n\t\t\t\t\"_type\": {\r\n\t\t\t\t\t\"$ref\": \"#/definitions/_type\"\r\n\t\t\t\t},\r\n\t\t\t\t\"_properties\": {\r\n\t\t\t\t\t\"type\": \"object\", \r\n\t\t\t\t\t\"properties\": {\r\n\t\t\t\t\t\t\"targetTemplatureCelsius\": {\r\n\t\t\t\t\t\t\t\"$ref\": \"#/definitions/targetTemplatureCelsius\"\r\n\t\t\t\t\t\t}\r\n\t\t\t\t\t}\r\n\t\t\t\t},\r\n\t\t\t\t\"links\": {\r\n\t\t\t\t\t\"$ref\": \"#/definitions/links\"\r\n\t\t\t\t}\r\n\t\t\t},\r\n\t\t\t\"forms\": [\r\n\t\t\t\t{\r\n\t\t\t\t\t\"href\": \"properties/targetTemplatureCelsius\"\r\n\t\t\t\t}\r\n\t\t\t]\r\n\t\t}\r\n\t},\r\n\t\"definitions\": {\r\n\t\t\"_id\": {\r\n\t\t\t\"title\": \"ID\",\r\n\t\t\t\"description\": \"ID of this device\",\r\n\t\t\t\"type\": \"string\",\r\n\t\t\t\"const\": \"urn:dev:wot:com:example:servient:homeAirConditioner:1\"\r\n\t\t},\r\n\t\t\"_type\": {\r\n\t\t\t\"title\": \"Type\",\r\n\t\t\t\"description\": \"Type of this device\",\r\n\t\t\t\"type\": \"string\",\r\n\t\t\t\"const\": \"homeAirConditioner\"\r\n\t\t},\r\n\t\t\"operationStatus\": {\r\n\t\t\t\"title\": \"Operation Status\",\r\n\t\t\t\"description\": \"Operational Status such as On and Off\",\r\n\t\t\t\"type\": \"boolean\"\r\n\t\t},\r\n\t\t\"targetTemplatureCelsius\": {\r\n\t\t\t\"title\": \"Target Temperature Celsius\",\r\n\t\t\t\"description\": \"Target Temperature in Celsius\",\r\n\t\t\t\"type\": \"number\",\r\n\t\t\t\"minimum\": 0.0,\r\n\t\t\t\"maximum\": 50.0,\r\n\t\t\t\"unit\": \"Celsius\"\r\n\t\t},\r\n\t\t\"links\": {\r\n\t\t\t\"title\": \"Links\",\r\n\t\t\t\"description\": \"Possible links of this device\",\r\n\t\t\t\"type\": \"array\",\r\n\t\t\t\"items\": {\r\n\t\t\t\t\"type\": \"object\",\r\n\t\t\t\t\"properties\": {\r\n\t\t\t\t\t\"rel\":  {\r\n\t\t\t\t\t\t\"type\": \"string\"\r\n\t\t\t\t\t}, \r\n\t\t\t\t\t\"href\": {\r\n\t\t\t\t\t\t\"type\": \"string\" \r\n\t\t\t\t\t}\r\n\t\t\t\t}\r\n\t\t\t}, \r\n\t\t\t\"readOnly\": true\r\n\t\t}\r\n\t}\r\n}\r\n```"},"comment":{"url":"https://api.github.com/repos/w3c/wot-thing-description/issues/comments/442389432","html_url":"https://github.com/w3c/wot-thing-description/issues/307#issuecomment-442389432","issue_url":"https://api.github.com/repos/w3c/wot-thing-description/issues/307","id":442389432,"node_id":"MDEyOklzc3VlQ29tbWVudDQ0MjM4OTQzMg==","user":{"login":"ToruKawaguchi","id":17423222,"node_id":"MDQ6VXNlcjE3NDIzMjIy","avatar_url":"https://avatars1.githubusercontent.com/u/17423222?v=4","gravatar_id":"","url":"https://api.github.com/users/ToruKawaguchi","html_url":"https://github.com/ToruKawaguchi","followers_url":"https://api.github.com/users/ToruKawaguchi/followers","following_url":"https://api.github.com/users/ToruKawaguchi/following{/other_user}","gists_url":"https://api.github.com/users/ToruKawaguchi/gists{/gist_id}","starred_url":"https://api.github.com/users/ToruKawaguchi/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ToruKawaguchi/subscriptions","organizations_url":"https://api.github.com/users/ToruKawaguchi/orgs","repos_url":"https://api.github.com/users/ToruKawaguchi/repos","events_url":"https://api.github.com/users/ToruKawaguchi/events{/privacy}","received_events_url":"https://api.github.com/users/ToruKawaguchi/received_events","type":"User","site_admin":false},"created_at":"2018-11-28T10:01:12Z","updated_at":"2018-11-28T10:01:12Z","author_association":"CONTRIBUTOR","body":"@egekorkan @handrews @mmccool Thank you for your comments ! I understood that above approach is currently beyond JSON-Schema and consequently beyond Thing Description specification. For now, I would  repeat schema definitions in each property.  \r\n\r\n"}}
{"actor":{"display_login":"ToruKawaguchi"}}