thing

package
v0.0.0-...-a67a4a9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 15, 2022 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package thing with API interface definitions for the ExposedThing and ConsumedThing classes

Package thing with API interface definitions for the ExposedThing and ConsumedThing classes

Package thing with API interface definitions for the ExposedThing and ConsumedThing classes

Package thing with API interface definitions for the ExposedThing and ConsumedThing classes

Package thing with schema type definitions for the ExposedThing and ConsumedThing classes as described here: https://www.w3.org/TR/wot-thing-description/#sec-data-schema-vocabulary-definition

Package thing with methods to handle Thing IDs

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CreatePublisherID 

func CreatePublisherID(zone string, publisher string, deviceID string, deviceType vocab.DeviceType) string

CreatePublisherID creates a globally unique Thing ID that includes the zone and publisher name where the Thing originates from. The publisher is especially useful where protocol bindings create thing IDs. In this case the publisher is the gateway used by the protocol binding or the PB itself. See also SplitThingID.

This creates a Thing ID: URN:zone:publisher:deviceID:deviceType 

zone is the name of the zone the device is part of. Use "" for local.
publisher is the deviceID of the publisher of the thing.
deviceID is the ID of the device to use as part of the Thing ID

func CreateThingID 

func CreateThingID(zone string, deviceID string, deviceType vocab.DeviceType) string

CreateThingID creates a ThingID from the zone it belongs to, the hardware device ID and device Type This creates a Thing ID: URN:zone:deviceID:deviceType. 

zone is the name of the zone the device is part of. Use "" for local.
deviceID is the ID of the device to use as part of the Thing ID.

func SplitThingID 

func SplitThingID(thingID string) (
	zone string, publisherID string, deviceID string, deviceType vocab.DeviceType)

SplitThingID takes a ThingID and breaks it down into individual parts. Supported formats: 

A full thingID with zone and publisher: URN:zone:publisherID:deviceID:deviceType.
A thingID without publisher: URN:zone:deviceID:deviceType
A thingID without zone: URN:deviceID:deviceType
A thingID without anything specific: URN:deviceID

Types

type ActionAffordance 

type ActionAffordance struct {
	InteractionAffordance

	// Define the input data schema of the action
	Input DataSchema `json:"input,omitempty"`

	// Defines the output data schema of the action
	Output DataSchema `json:"output,omitempty"`

	// Signals if the Action is state safe (=true) or not
	// Safe actions do not change the internal state of a resource
	Safe bool `json:"safe,omitempty" default:"false"`

	// Indicate whether the action is idempotent, eg repeated calls with the same result
	Idempotent bool `json:"idempotent,omitempty" default:"false"`
}

ActionAffordance metadata that defines how to invoke a function of a Thing to manipulate its state, eg toggle lamp on/off or trigger a process

type DataSchema 

type DataSchema struct {
	// JSON-LD keyword to label the object with semantic tags (or types)
	// Used to indicate input, output, attribute. See vocab.WoSTAtType
	AtType string `json:"@type,omitempty"`
	// Provides a human-readable title in the default language
	Title string `json:"title,omitempty"`
	// Provides a multi-language human-readable titles
	Titles []string `json:"titles,omitempty"`
	// Provides additional (human-readable) information based on a default language
	Description string `json:"description,omitempty"`
	// Provides additional nulti-language information
	Descriptions []string `json:"descriptions,omitempty"`
	// Provides a constant value of any type as per data schema
	Const interface{} `json:"const,omitempty"`
	// Provides a default value of any type as per data schema
	Default interface{} `json:"default,omitempty"`
	// Unit as used in international science, engineering, and business.
	// See vocab UnitNameXyz for units in the WoST vocabulary
	Unit string `json:"unit,omitempty"`
	// OneOf provides constraint of data as one of the given data schemas
	OneOf []interface{} `json:"oneOf,omitempty"`
	// Restricted set of values provided as an array.
	//  for example: ["option1", "option2"]
	Enum []interface{} `json:"enum,omitempty"`
	// Boolean value to indicate whether a property interaction / value is read-only (=true) or not (=false)
	// the value true implies read-only.
	ReadOnly bool `json:"readOnly,omitempty"`
	// Boolean value to indicate whether a property interaction / value is write-only (=true) or not (=false)
	// the value true implies writable, except when ReadOnly is true.
	WriteOnly bool `json:"writeOnly,omitempty"`
	// Allows validation based on a format pattern such as "date-time", "email", "uri", etc.
	// See vocab DataFormXyz "date-time", "email", "uri" (todo)
	Format string `json:"format,omitempty"`
	// Type provides JSON based data type,  one of WoTDataTypeNumber, ...object, array, string, integer, boolean or null
	Type string `json:"type,omitempty"`

	// ArraySchema with metadata describing data of type Array.
	// https://www.w3.org/TR/wot-thing-description/#arrayschema
	// Used to define the characteristics of an array.
	// Note that in golang a field cannot both be a single or an array of items.
	ArrayItems interface{} `json:"items,omitempty"`
	// Defines the minimum number of items that have to be in the array
	ArrayMinItems uint `json:"minItems,omitempty"`
	// Defines the maximum number of items that have to be in the array.
	ArrayMaxItems uint `json:"maxItems,omitempty"`

	// NumberSchema with metadata describing data of type number.
	// This Subclass is indicated by the value number assigned to type in DataSchema instances.
	// Maximum specifies a maximum numeric value representing an upper limit
	NumberMaximum float64 `json:"maximum,omitempty"`
	// Minimum specifies a minimum numeric value representing a lower limit
	NumberMinimum float64 `json:"minimum,omitempty"`

	// ObjectSchema with metadata describing data of type Object.
	// This Subclass is indicated by the value object assigned to type in DataSchema instances.
	// Properties of Object.
	Properties map[string]DataSchema `json:"properties,omitempty"`
	// Defines which members of the object type are mandatory
	PropertiesRequired []string `json:"required,omitempty"`

	// StringSchema with metadata describing data of type string.
	// This Subclass is indicated by the value string assigned to type in DataSchema instances.
	// MaxLength specifies the maximum length of a string
	StringMaxLength uint `json:"maxLength,omitempty"`
	// MinLength specifies the minimum length of a string
	StringMinLength uint `json:"minLength,omitempty"`
	// Pattern provides a regular expression to express constraints.
	// The regular expression must follow the [ECMA-262] dialect.	optional
	StringPattern string `json:"pattern,omitempty"`
	// ContentEncoding specifies the encoding used to store the contents, as specified in RFC 2054.
	// e.g., 7bit, 8bit, binary, quoted-printable, or base64
	StringContentEncoding string `json:"contentEncoding,omitempty"`
	// ContentMediaType specifies the MIME type of the contents of a string value, as described in RFC 2046.
	// e.g., image/png, or audio/mpeg)
	StringContentMediaType string `json:"contentMediaType,omitempty"`
}

DataSchema with metadata that describes the data format used. It can be used for validation.

Golang doesn't support dynamic types or subclasses, so DataSchema merges all possible schemas including string, number, integer, object, array,...

based on https://www.w3.org/TR/wot-thing-description/#dataschema

type EventAffordance 

type EventAffordance struct {
	InteractionAffordance

	// Data schema of the event instance message, eg the event payload
	Data DataSchema `json:"data,omitempty"`
}

EventAffordance with metadata that describes an event source, which asynchronously pushes event data to Consumers (e.g., overheating alerts).

type Form 

type Form struct {
	Href        string `json:"href"`
	ContentType string `json:"contentType"`

	// operations types of a form as per https://www.w3.org/TR/wot-thing-description11/#form
	// readproperty, writeproperty, ...
	Op string `json:"op"`
}

Form can be viewed as a statement of "To perform an operation type operation on form context, make a request method request to submission target" where the optional form fields may further describe the required request. In Thing Descriptions, the form context is the surrounding Object, such as Properties, Actions, and Events or the Thing itself for meta-interactions. (I this isn't clear then you are not alone)

type InteractionAffordance 

type InteractionAffordance struct {
	// JSON-LD keyword to label the object with semantic tags (or types)
	AtType string `json:"@type,omitempty"`
	// Provides a human-readable title in the default language
	Title string `json:"title,omitempty"`
	// Provides a multi-language human-readable titles
	Titles []string `json:"titles,omitempty"`
	// Provides additional (human-readable) information based on a default language
	Description string `json:"description,omitempty"`
	// Provides additional nulti-language information
	Descriptions []string `json:"descriptions,omitempty"`

	// Form hypermedia controls to describe how an operation can be performed
	// Forms are serializations of Protocol Bindings.
	Forms []Form `json:"forms"`

	// Define URI template variables according to [RFC6570] as collection based on DataSchema declarations.
	// ... right
	UriVariables map[string]DataSchema `json:"uriVariables,omitempty"`
}

InteractionAffordance metadata of a Thing that suggests to Consumers how to interact with the Thing This is a DataSchema for the purpose of defining property, actions and events

type PropertyAffordance 

type PropertyAffordance struct {
	DataSchema

	// Form hypermedia controls to describe how an operation can be performed
	// Forms are serializations of Protocol Bindings.
	Forms []Form `json:"forms,omitempty"`

	// Define URI template variables according to [RFC6570] as collection based on DataSchema declarations.
	// ... right
	UriVariables map[string]DataSchema `json:"uriVariables,omitempty"`

	// Optional nested properties. Map with PropertyAffordance
	Properties map[string]PropertyAffordance `json:"properties,omitempty"`
}

PropertyAffordance metadata that defines Thing properties This is a Subclass of the InteractionAffordance Class and the DataSchema Class. Note: https://github.com/w3c/wot-thing-description/issues/1390 The spec simply cannot be implemented in golang without dynamic types. PropertyAffordance must be able to have a schema based on the type, not just DataSchema, as a property can be of any of the types integer, boolean, object, array, number...

type ThingTD 

type ThingTD struct {
	// JSON-LD keyword to define short-hand names called terms that are used throughout a TD document. Required.
	AtContext []string `json:"@context"`

	// JSON-LD keyword to label the object with semantic tags (or types).
	AtType  string `json:"@type,omitempty"`
	AtTypes string `json:"@types,omitempty"`

	// base: Define the base URI that is used for all relative URI references throughout a TD document.
	Base string `json:"base,omitempty"`

	// ISO8601 timestamp this document was first created
	Created string `json:"created,omitempty"`
	// ISO8601 timestamp this document was last modified
	Modified string `json:"modified,omitempty"`

	// Provides additional (human-readable) information based on a default language
	Description string `json:"description,omitempty"`
	// Provides additional nulti-language information
	Descriptions []string `json:"descriptions,omitempty"`

	// Identifier of the Thing in form of a URI (RFC3986)
	// Optional in WoT but required in WoST in order to reach the device or service
	ID string `json:"id"`

	// Information about the TD maintainer as URI scheme (e.g., mailto [RFC6068], tel [RFC3966], https).
	Support string `json:"support,omitempty"`

	// Human-readable title in the default language. Required.
	Title string `json:"title"`
	// Human-readable titles in the different languages
	Titles map[string]string `json:"titles,omitempty"`

	// All properties-based interaction affordances of the thing
	Properties map[string]*PropertyAffordance `json:"properties,omitempty"`
	// All action-based interaction affordances of the thing
	Actions map[string]*ActionAffordance `json:"actions,omitempty"`
	// All event-based interaction affordances of the thing
	Events map[string]*EventAffordance `json:"events,omitempty"`

	// Form hypermedia controls to describe how an operation can be performed. Forms are serializations of
	// Protocol Bindings. Thing-level forms are used to describe endpoints for a group of interaction affordances.
	Forms []Form `json:"forms,omitempty"`

	// Set of security definition names, chosen from those defined in securityDefinitions
	// In WoST security is handled by the Hub. WoST Things will use the NoSecurityScheme type
	Security string `json:"security"`
	// Set of named security configurations (definitions only).
	// Not actually applied unless names are used in a security name-value pair. (why is this mandatory then?)
	SecurityDefinitions map[string]string `json:"securityDefinitions,omitempty"`
	// contains filtered or unexported fields
}

ThingTD contains the Thing Description document Its structure is: 

{
     @context: "http://www.w3.org/ns/td",
     @type: <deviceType>,
     id: <thingID>,
     title: <human description>,  (why is this not a property?)
     modified: <iso8601>,
     actions: {name: ActionAffordance, ...},
     events:  {name: EventAffordance, ...},
     properties: {name: PropertyAffordance, ...}
}

func CreateTD 

func CreateTD(thingID string, title string, deviceType vocab.DeviceType) *ThingTD

CreateTD creates a new Thing Description document with properties, events and actions Its structure: 

{
     @context: "http://www.w3.org/ns/td",
     id: <thingID>,      		// required in WoST. See CreateThingID for recommended format
     title: string,              // required. Human description of the thing
     @type: <deviceType>,        // required in WoST. See WoST DeviceType vocabulary
     created: <iso8601>,         // will be the current timestamp. See vocabulary TimeFormat
     actions: {name:TDAction, ...},
     events:  {name: TDEvent, ...},
     properties: {name: TDProperty, ...}
}

func (*ThingTD) AddAction 

func (tdoc *ThingTD) AddAction(name string, title string, dataType string) *ActionAffordance

AddAction provides a simple way to add an action affordance schema to the TD This returns the action affordance that can be augmented/modified directly

name is the name under which it is stored in the action affordance map. Any existing name will be replaced. title is the title used in the action. It is okay to use name if not sure. dataType is the type of data the action holds, WoTDataTypeNumber, ..Object, ..Array, ..String, ..Integer, ..Boolean or null

func (*ThingTD) AddEvent 

func (tdoc *ThingTD) AddEvent(name string, title string, dataType string) *EventAffordance

AddEvent provides a simple way to add an event to the TD This returns the event affordance that can be augmented/modified directly

name is the name under which it is stored in the property affordance map. Any existing name will be replaced. title is the title used in the event. It is okay to use name if not sure. dataType is the type of data the event holds, WoTDataTypeNumber, ..Object, ..Array, ..String, ..Integer, ..Boolean or null

func (*ThingTD) AddProperty 

func (tdoc *ThingTD) AddProperty(name string, title string, dataType string) *PropertyAffordance

AddProperty provides a simple way to add a property to the TD This returns the property affordance that can be augmented/modified directly By default the property is a read-only attribute.

name is the name under which it is stored in the property affordance map. Any existing name will be replaced. title is the title used in the property. It is okay to use name if not sure. dataType is the type of data the property holds, WoTDataTypeNumber, ..Object, ..Array, ..String, ..Integer, ..Boolean or null

func (*ThingTD) AsMap 

func (tdoc *ThingTD) AsMap() map[string]interface{}

AsMap returns the TD document as a map

func (*ThingTD) GetAction 

func (tdoc *ThingTD) GetAction(name string) *ActionAffordance

GetAction returns the action affordance with schema for the action. Returns nil if name is not an action or no affordance is defined.

func (*ThingTD) GetEvent 

func (tdoc *ThingTD) GetEvent(name string) *EventAffordance

GetEvent returns the schema for the event or nil if the event doesn't exist

func (*ThingTD) GetID 

func (tdoc *ThingTD) GetID() string

GetID returns the ID of the thing TD

func (*ThingTD) GetProperty 

func (tdoc *ThingTD) GetProperty(name string) *PropertyAffordance

GetProperty returns the schema and value for the property or nil if name is not a property

func (*ThingTD) UpdateAction 

func (tdoc *ThingTD) UpdateAction(name string, affordance *ActionAffordance) *ActionAffordance

UpdateAction adds a new or replaces an existing action affordance (schema) of name. Intended for creating TDs Use UpdateProperty if name is a property name. Returns the added affordance to support chaining

func (*ThingTD) UpdateEvent 

func (tdoc *ThingTD) UpdateEvent(name string, affordance *EventAffordance) *EventAffordance

UpdateEvent adds a new or replaces an existing event affordance (schema) of name. Intended for creating TDs Returns the added affordance to support chaining

func (*ThingTD) UpdateForms 

func (tdoc *ThingTD) UpdateForms(formList []Form)

UpdateForms sets the top level forms section of the TD NOTE: In WoST actions are always routed via the Hub using the Hub's protocol binding. Under normal circumstances forms are therefore not needed.

func (*ThingTD) UpdateProperty 

func (tdoc *ThingTD) UpdateProperty(name string, affordance *PropertyAffordance) *PropertyAffordance

UpdateProperty adds or replaces a property affordance in the TD. Intended for creating TDs Returns the added affordance to support chaining

func (*ThingTD) UpdateTitleDescription 

func (tdoc *ThingTD) UpdateTitleDescription(title string, description string)

UpdateTitleDescription sets the title and description of the Thing in the default language

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.