# LV2 Patch

A protocol for accessing and manipulating properties.

ID | http://lv2plug.in/ns/ext/patch
Version | 2.8
Date | 2021-01-09
Discuss | devel@lists.lv2plug.in (subscribe)

- Index
- History
- API

This is a vocabulary for messages that access and manipulate properties. It can be used as a dynamic control interface for plugins, or anything else with a property-based model.

The key underlying concept here is to control things by manipulating arbitrary properties, rather than by calling application-specific methods. This allows implementations to understand what messages do (at least in a mechanical sense), which makes things like caching, proxying, or undo relatively straightforward to implement. Note, however, that this is only conceptual: there is no requirement to implement a general property store. Typically, a plugin will understand a fixed set of properties that represent its parameters or other internal state, and ignore everything else.

This protocol is syntax-agnostic, and homoiconic in the sense that the messages use the same format as the data they manipulate. In particular, messages can be serialised as a binary Object for realtime plugin control, or as Turtle for saving to a file, sending over a network, printing for debugging purposes, and so on.

This specification only defines a semantic protocol, there is no corresponding API. It can be used with the Atom extension to control plugins which support message-based parameters as defined by the Parameters extension.

For example, if a plugin defines a `eg:volume` parameter, it can be controlled by the host by sending a Set message to the plugin instance:

    [
        a patch:Set ;
        patch:property eg:volume ;
        patch:value 11.0 ;
    ]

Similarly, the host could get the current value for this parameter by sending a Get message:

    [
        a patch:Get ;
        patch:property eg:volume ;
    ]

The plugin would then respond with the same Set message as above. In this case, the plugin instance is implicitly the subject, but a specific subject can also be given for deeper control.

## Index

Classes | Properties | Instances
--- | --- | ---
Message Request Copy Delete Get Insert Move Patch Put Set Response Ack Error | accept add body context destination property readable remove request sequenceNumber subject value writable | wildcard

## Classes

### Ack

Class

Label | Ack
Subclass of | Response

An acknowledgement that a request was successful.

### Copy

Class

Label | Copy
Subclass of | Request

A request to copy the subject to the destination.

After this, the destination has the same description as the subject, and the subject is unchanged.

It is an error if the subject does not exist, or if the destination already exists.

Multiple subjects may be given if the destination is a container, but the semantics of this case are application-defined.

Restriction on subject
  owl:minCardinality 1
Restriction on destination
  owl:cardinality 1

### Delete

Class

Label | Delete
Subclass of | Request

Request that the subject or subjects be deleted.

### Error

Class

Label | Error
Subclass of | Response

A response indicating an error processing a request.

### Get

Class

Label | Get
Subclass of | Request

A request for a description of the subject.

If a property is given, then the receiver should respond with a Set message that gives only that property.

Otherwise, it should respond with a concise bounded description in a Put message, that is, a description that recursively includes any blank node values.

If a subject is given, then the response should have the same subject. If no subject is given, then the receiver is implicitly the subject.

If a request node or a sequenceNumber is given, then the response should be a Response and have the same property. If neither is given, then the receiver can respond with a simple Put message. For example:

    []
        a patch:Get ;
        patch:subject eg:something .

Could result in:

    []
        a patch:Put ;
        patch:subject eg:something ;
        patch:body [
            eg:name "Something" ;
            eg:ratio 1.6180339887 ;
        ] .

### Insert

Class

Label | Insert
Subclass of | Request

A request to insert a body into the subject.

If the subject does not exist, it is created. If the subject does already exist, it is added to.

This request only adds properties, it never removes them. The user must take care that multiple values are not set for properties which should only have one.

Restriction on subject
  owl:cardinality 1

### Message

Class

Label | Patch Message
Superclass of | Request
| Response
In domain of | body
| context
| destination
| property
| sequenceNumber
| subject

A patch message.

This is an abstract base class for all patch messages. Concrete messages are either a Request or a Response.

### Move

Class

Label | Move
Subclass of | Request

A request to move the subject to the destination.

After this, the destination has the description that the subject had, and the subject no longer exists.

It is an error if the subject does not exist, or if the destination already exists.

Restriction on subject
  owl:cardinality 1
Restriction on destination
  owl:cardinality 1

### Patch

Class

Label | Patch
Subclass of | Request
In domain of | add
| remove

A request to add and/or remove properties of the subject.

This method always has at least one subject, and exactly one add and remove property. The value of add and remove are nodes which have the properties to add or remove from the subject(s), respectively. The special value wildcard may be used as the value of a remove property to remove all properties with the given predicate. For example:

    []
        a patch:Patch ;
        patch:subject <something> ;
        patch:add [
            eg:name "New name" ;
            eg:age 42 ;
        ] ;
        patch:remove [
            eg:name "Old name" ;
            eg:age patch:wildcard ;  # Remove all old eg:age properties
        ] .

Restriction on subject
  owl:minCardinality 1
Restriction on add
  owl:cardinality 1
Restriction on remove
  owl:cardinality 1

### Put

Class

Label | Put
Subclass of | Request

A request to put the body as the subject.

If the subject does not already exist, it is created. If the subject does already exist, the body is considered an updated version of it, and the previous version is replaced.

    []
        a patch:Put ;
        patch:subject <something> ;
        patch:body [
            eg:name "New name" ;
            eg:age 42 ;
        ] .

Restriction on subject
  owl:cardinality 1

### Request

Class

Label | Request
Subclass of | Message
Superclass of | Copy
| Delete
| Get
| Insert
| Move
| Patch
| Put
| Set
In domain of | accept
In range of | request

A patch request message.

A request may have a subject property, which specifies the resource that the request applies to. The subject may be omitted in contexts where it is implicit, for example if the recipient is the subject.

### Response

Class

Label | Response
Subclass of | Message
Superclass of | Ack
| Error
In domain of | request

A response to a Request.

### Set

Class

Label | Set
Subclass of | Request
In domain of | value

A compact request to set a property to a value.

This is equivalent to a Patch which removes all pre-existing values for the property before setting the new value. For example:

    []
        a patch:Set ;
        patch:subject <something> ;
        patch:property eg:name ;
        patch:value "New name" .

Which is equivalent to:

    []
        a patch:Patch ;
        patch:subject <something> ;
        patch:add [
            eg:name "New name" ;
        ] ;
        patch:remove [
            eg:name patch:wildcard ;
        ] .

Restriction on property
  owl:cardinality 1
Restriction on value
  owl:cardinality 1

## Properties

### accept

Property

Label | accept
Domain | Request
Range | rdfs:Class
Type | Object Property

An accepted type for a response.

### add

Property

Label | add
Domain | Patch
Range | rdfs:Resource
Type | Object Property

The properties to add to the subject.

### body

Property

Label | body
Domain | Message
Type | Object Property

The body of a message.

The details of this property's value depend on the type of message it is a part of.

### context

Property

Label | context
Domain | Message
Type | Object Property

The context of properties in this message.

For example, a plugin may have a special context for ephemeral properties which are only relevant during the lifetime of the instance and should not be saved in state.

The specific uses for contexts are application specific. However, the context MUST be a URI, and can be interpreted as the ID of a data model where properties should be stored. Implementations MAY have special support for contexts, for example by storing in a quad store or serializing to a format that supports multiple RDF graphs such as TriG.

### destination

Property

Label | destination
Domain | Message
Type | Object Property

The destination to move the subject to.

### property

Property

Label | property
Domain | Message
Range | rdf:Property
Type | Object Property

The property for a Set or Get message.

### readable

Property

Label | readable
Range | rdf:Property
Type | Object Property

A property that can be read with a Get message.

See the similar writable property for details.

### remove

Property

Label | remove
Domain | Patch
Range | rdfs:Resource
Type | Object Property

The properties to remove from the subject.

### request

Property

Label | request
Domain | Response
Range | Request
Type | Object Property

The request this is a response to.

This can be used if referring directly to the URI or blank node ID of the request is possible. Otherwise, use sequenceNumber.

### sequenceNumber

Property

Label | sequence number
Domain | Message
Range | xsd:int
Type | Datatype Property

The sequence number of a request or response.

This property is used to associate replies with requests when it is not feasible to refer to request URIs with request. A Response with a given sequence number is the reply to the previously send Request with the same sequence number.

The special sequence number 0 means that no reply is desired.

### subject

Property

Label | subject
Domain | Message
Type | Object Property

The subject this message applies to.

### value

Property

Label | value
Domain | Set
Range | rdf:Property
Type | Datatype Property

The value of a property in a Set message.

### writable

Property

Label | writable
Range | rdf:Property
Type | Object Property

A property that can be set with a Set or Patch message.

This is used to list properties that can be changed, for example to allow user interfaces to present appropriate controls. For example:

    @prefix eg:   <http://example.org/> .
    @prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
    @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
    @prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .

    eg:title
        a rdf:Property ;
        rdfs:label "title" ;
        rdfs:range xsd:string .

    eg:plugin
        patch:writable eg:title .

## Instances

### wildcard

Instance

Label | wildcard
Type | rdfs:Resource

A wildcard that matches any resource.

This makes it possible to describe the removal of all values for a given property.

## History

Version 2.8 (2020-04-26)
  - Fix incorrect type of patch:sequenceNumber.
Version 2.6 (2019-02-03)
  - Add patch:accept property.
  - Add patch:context property.
Version 2.4 (2015-04-07)
  - Define patch:Get with no subject to implicitly apply to reciever. This can be used by UIs to get an initial description of a plugin.
  - Add patch:Copy method.
Version 2.2 (2014-08-08)
  - Add patch:sequenceNumber for associating replies with requests.
Version 2.0 (2013-01-10)
  - Make patch:Set a compact message for setting one property.
  - Add patch:readable and patch:writable for describing available properties.
Version 1.0 (2012-04-17)
  - Initial release.