The Edit Service (used by EDG Forms)

TopBraid Live includes a servlet that can be used to perform changes (updates) to an RDF graph managed by TopBraid.

From version 6.1 onwards, this feature is no longer supported for external customers. Users are encouraged to switch to TopBraid's GraphQL service as an alternative to this service here. If you do try GraphQL, please provide us with your feedback.

The name of the service is swpEdit. This service is used internally by the EDG forms, but can also be called by 3rd party applications to implement data-driven forms. To create such data-driven form, you may want to use the template services provided by TopBraid to learn about the available and actual properties of a given resource. Go to the TBL help page on available web services and select http://topbraid.org/swa.spin. For example, the service swa:GetRelevantPropertiesOfClass gets all properties that should appear on a data entry form for a new instance of a class. More services can be created via SPIN templates or SWP services if needed.

Parameters

The servlet takes an arbitrary number of parameters following the patterns shown below:

resource-1 = <http://example.org/JohnDoe>    # The subject to change
path-1 = <http://example.org/firstName>      # The predicate to change (might be inverse)
old-1 = John                                 # The old value to replace
new-1 = Johannes                             # The new value to use (or nothing to delete)

Parameters are grouped by their suffix, e.g. all parameters ending with "-1" are treated as one group that changes exactly one value. The suffix doesn't need to be a number, but any string such "-uniqueIdA" would work too. The servlet has been designed to be easy to use from HTML forms that submit changes using name-value pairs. Each group represents one widget on the form. The corresponding HTML for the service call above could be:

<div class="editWidget">
    <input type="hidden" name="resource-1" value="&lt;http://example.org/JohnDoe&gt;" />
    <input type="hidden" name="path-1" value="&lt;http://example.org/firstName&gt;" />
    <input type="hidden" name="old-1" value="&quot;John&quot;^^xsd:string" />
    <span class="label">First name:</span>
    <input type="text" name="new-1" value="John" />   <!-- This is entered by user -->
</div>

The parameters must follow these patterns. Note that URI resources are encoded either as qname using the prefixes of the current base graph (e.g. schema:givenName) or a URI wrapped with <...> (e.g. <http://schema.org/givenName>).

• _base must be the URI of the graph that is edited.
• resource-X is mandatory and needs to be a URI the base graph.
• path-X is mandatory and needs to either be a property (again, resolvable with the current base graph) or a property preceeded by the minus character to represent an inverse path. For example -skos:broader would replace the subject where the resource is the object of a triple.
• old-X the SPARQL-encoded value that shall be replaced. Nothing for new values.
• new-X the lexical form of the new value, interpreted depending on datatype and lang parameters.
• lang-X the language of the new literal, e.g. "en". "" means a typed string literal. null (unbound) means that it is either a typed literal or a resource.
• datatype-X the encoded URI of the datatype or null to decode new-X as a URI resource.

Constraint Validation

Before making the changes, the servlet will simulate the edit in a local graph and verify whether the changes would lead to any new (SPIN) constraint violations. By default, if any constraint is violated for the given resource, the edit will be rejected. However, if the parameter warningsAccepted is set to true then non-critical SPIN constraint violations will be allowed to pass through. In a typical scenario, the UI would invoke the service without the warningsAccepted flag and then call it again if the user has OKed the changes, and then with the flag set to true. The only constraint that will never be allowed to pass is if the resource loses its (last) rdf:type triple.

The parameter validateOnly=true indicates that no edits shall be performed but the servlet shall still validate the constraints. The output JSON (see below) will then only include the violations. While this service can be called via Ajax to validate input after any change by the user, EDG forms only perform validation when the user hits the Save Changes button.

Response

The response of the servlet is a JSON structure that can be used to update the UI selectively. In the following example, the edit was successful and "Benin" was renamed leading to labelChanges that could be used to refresh tree nodes etc. The user had also deleted a value for skos:related. Changes to literal triples are currently not reported.

{ 
    "changed" : true ,
    "added" : 2 ,
    "deleted" : 2 ,
    "changes" : { 
        "http://tests.evn.topbraid.org/geo/geo#Benin" : 
        { 
            "-http://www.w3.org/2004/02/skos/core#related" : [ "http://tests.evn.topbraid.org/geo/geo#Sub-Saharan_Africa" ] 
        }
    } ,
    "labelChanges" : { "http://tests.evn.topbraid.org/geo/geo#Benin" : "Benign" } ,
    "rootResource" : "http://tests.evn.topbraid.org/geo/geo#Benin"
}

If there have been critical constraint violations, then the response would look like:

{
    "changed" : "false" ,
    "errors" : [ 
        {   "message" : "The edited resource must have a type" ,
            "path" : "http://www.w3.org/1999/02/22-rdf-syntax-ns#type" ,
            "root" : "http://tests.evn.topbraid.org/geo/geo#Benin"
        } 
    ]
}

Uncritical SPIN constraint violations look like:

{
    "changed" : false ,
    "rootResource" : "http://tests.evn.topbraid.org/geo/geo#Benin" ,
    "warnings" : [ 
        {   "message" : "Constraint S13: A concept can't have the same value in the same language in both altLabel and prefLabel - duplicate value: Benign" ,
            "path" : "http://www.w3.org/2004/02/skos/core#altLabel" ,
            "root" : "http://tests.evn.topbraid.org/geo/geo#Benin"
        } 
    ]
}

You can experiment with those JSON results by performing some edits with EDG with a debugging tool such as FireBug running in your browser.