thing

package
v0.0.0-...-2920ad6 Latest Latest
Warning

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

 Go to latest Published: Jan 1, 2023 License: MIT Imports: 7 Imported by: 13

Documentation

Overview

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 API interface definitions for the ExposedThing and ConsumedThing classes

Package thing with API interface definitions for forms

Package thing with handling of property, event and action values

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsPublisher 

func IsPublisher(publisherID string, thingAddr string) bool

IsPublisher tests whether the given thingAddr is of the given publisher Returns true if it is.

func MakeThingAddr 

func MakeThingAddr(publisherID string, thingID string) string

MakeThingAddr implements the definition of a Thing's address, eg the publisherID / ThingID If publisherID is empty, only the thingID will be included This is the de-facto method of constructing a thing's address out of the ThingID's of its publisher and itself

func SplitThingAddr 

func SplitThingAddr(thingAddr string) (publisherID string, thingID string)

SplitThingAddr split the thing address in its publisherID and thingID parts If only a single part is found then this is the thingID and publisherID will be empty ""

Types

type ActionAffordance 

type ActionAffordance struct {
	//---InteractionAffordance starts
	// 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"`

	// 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.AtType
	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 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 starts
	// 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"`

	// 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 InteractionOutput 

type InteractionOutput struct {
	// Schema describing the data from property, event or action affordance
	Schema *DataSchema

	// decoded data in its native format, eg string, int, array, object
	Value interface{} `json:"value"`
	// contains filtered or unexported fields
}

InteractionOutput to expose the data returned from WoT Interactions to applications. Use NewInteractionOutput to initialize

func NewInteractionOutput 

func NewInteractionOutput(data interface{}, schema *DataSchema) *InteractionOutput

NewInteractionOutput creates a new interaction output from object data data is native that will be json encoded using the given Schema Schema describes the value. nil in case of unknown Schema

func NewInteractionOutputFromJson 

func NewInteractionOutputFromJson(jsonEncoded []byte, schema *DataSchema) *InteractionOutput

NewInteractionOutputFromJson creates a new interaction output for reading output data @param jsonEncoded is raw data that will be json parsed using the given Schema @param Schema describes the value. nil in case of unknown Schema

func (*InteractionOutput) ValueAsArray 

func (io *InteractionOutput) ValueAsArray() []interface{}

ValueAsArray returns the value as an array The result depends on the Schema type 

array: returns array of values as describe ni the Schema
boolean: returns a single element true/false
bytes: return an array of bytes
int: returns a single element with integer
object: returns a single element with object
string: returns a single element with string

func (*InteractionOutput) ValueAsBoolean 

func (io *InteractionOutput) ValueAsBoolean() bool

ValueAsBoolean returns the value as a boolean

func (*InteractionOutput) ValueAsInt 

func (io *InteractionOutput) ValueAsInt() int

ValueAsInt returns the value as an integer

func (*InteractionOutput) ValueAsMap 

func (io *InteractionOutput) ValueAsMap() map[string]interface{}

ValueAsMap returns the value as a key-value map Returns nil if no data was provided.

func (*InteractionOutput) ValueAsString 

func (io *InteractionOutput) ValueAsString() string

ValueAsString returns the value as a string

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 ThingDescription 

type ThingDescription 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
}

ThingDescription 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) *ThingDescription

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 (*ThingDescription) AddAction 

func (tdoc *ThingDescription) 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 (*ThingDescription) AddEvent 

func (tdoc *ThingDescription) 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 (*ThingDescription) AddProperty 

func (tdoc *ThingDescription) 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 (*ThingDescription) AsMap 

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

AsMap returns the TD document as a map

func (*ThingDescription) GetAction 

func (tdoc *ThingDescription) 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 (*ThingDescription) GetEvent 

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

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

func (*ThingDescription) GetID 

func (tdoc *ThingDescription) GetID() string

GetID returns the ID of the thing TD

func (*ThingDescription) GetProperty 

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

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

func (*ThingDescription) UpdateAction 

func (tdoc *ThingDescription) 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 (*ThingDescription) UpdateEvent 

func (tdoc *ThingDescription) 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 (*ThingDescription) UpdateForms 

func (tdoc *ThingDescription) 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 (*ThingDescription) UpdateProperty 

func (tdoc *ThingDescription) 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 (*ThingDescription) UpdateTitleDescription 

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

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

type ThingValue 

type ThingValue struct {
	// Address of the thing related to the value
	// Addresses are publisherID/thingID
	ThingAddr string

	// Name of event or action as described in the thing TD
	Name string

	// Event Value, JSON encoded
	ValueJSON []byte

	// Timestamp the value was created, in ISO8601 UTC format. Default "" is 'now'
	Created string
}

ThingValue contains an event, action value or TD of a thing

func NewThingValue 

func NewThingValue(thingAddr, name string, value []byte) *ThingValue

NewThingValue creates a new ThingValue object with the address of the thing, the value name and the serialized value This copies the value buffer.

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.