Difference between revisions of "Resource Registry Service - Type Management"
Luca.frosini (Talk | contribs) m (→Type Management) |
Luca.frosini (Talk | contribs) (→Type Definition) |
||
Line 41: | Line 41: | ||
* '''abstractType''' (Boolean): Indicate if the type is abstract so that it cannot be instantiated. In other words, only subtypes of this type can be instantiated. <code>default=false</code>. | * '''abstractType''' (Boolean): Indicate if the type is abstract so that it cannot be instantiated. In other words, only subtypes of this type can be instantiated. <code>default=false</code>. | ||
* '''superclasses''' (List<String>): The list of all supertypes of this type. Multiple Inheritance is supported. | * '''superclasses''' (List<String>): The list of all supertypes of this type. Multiple Inheritance is supported. | ||
− | * | + | * '''properties''': any types, except Resource and its specialisation, includes a properties array [List]. Any [[#Property] is described by a set of attributes. |
+ | * '''version''': the actual version of the type; | ||
+ | * '''changelog''': the history of changes in the type representation. It is an object containing properties with version as key and the change description as values. | ||
===== Property ===== | ===== Property ===== | ||
Line 47: | Line 49: | ||
Any [[Facet_Based_Resource_Model#Property | Property]] is described by the following attributes: | Any [[Facet_Based_Resource_Model#Property | Property]] is described by the following attributes: | ||
− | * '''name''' : | + | ** '''name'''*: the property name [String]; |
− | * '''type''' : The Type of the Property (e.g. String, Integer, ...). See [[#Property_Type|Property Type]] | + | ** '''type'''*: The Type of the Property (e.g. String, Integer, ...). See [[#Property_Type|Property Type]]; |
− | * '''description''' : | + | ** '''description''': the description of the property [String, default=null]; |
− | * '''mandatory''' : | + | ** '''mandatory''': indicate if the property is mandatory or not [String, default=false]; |
− | * '''readOnly''' : | + | ** '''readOnly''': the property cannot change its value [Boolean, default=false]; |
− | * '''notNull''' : | + | ** '''notNull''': whether the property must assume a value diverse from ’null’ or not [Boolean, default=false]; |
− | * '''max''' : | + | ** '''max''': whether the property can be limited to a maximum value [Integer, default=null]; |
− | * '''min''' : | + | ** '''min''': whether the property can be limited to a minimum value [Integer, default=null]; |
− | * ''' | + | ** '''regex''': a [https://en.wikipedia.org/wiki/Regular_expression regular expression] to validate the property value [String, default=null]. A good online tool for regex is available at [https://regex101.com/ https://regex101.com/] |
+ | |||
+ | |||
====== Property Type Mapping ====== | ====== Property Type Mapping ====== |
Revision as of 09:38, 2 July 2021
These sections provide information regarding how to interact with Resource Registry Service for Type Management. REST API are presented for each functionality.
Please note that the provided examples can intentionally hide some details in the response to avoid unneeded complexity.
Type Management
Type Management is responsible for managing the instantiation of the IS Model by allowing the definition of entities, relations and embedded types and their schema.
The exposed APIs are:
- Create: allows to create a new Type;
- Exists: allows to check if a Type exists;
- Read: allows to read a Type. This API allows also the listing of type and its subtypes by indicating hte query parameter polymorphic=true.
By indicating the polimorphic parameter and as {TYPE_NAME} on of the base type of the IS Model (i.e. Resource, Facet, IsRelatedTo, ConsistsOf), it is possibile to list all the types of such base type.
Type Collection
Operation | HTTP Method | URL |
---|---|---|
Create | PUT | /types/{TYPE_NAME}
|
Exists | HEAD | /types/{TYPE_NAME}
|
Read | GET | /types/{TYPE_NAME}[?polymorphic=false]
|
Type Definition
Any Type is described by the following attributes:
- name (String): Type Name
- description (String): The description of the Type.
default=null
. - abstractType (Boolean): Indicate if the type is abstract so that it cannot be instantiated. In other words, only subtypes of this type can be instantiated.
default=false
. - superclasses (List<String>): The list of all supertypes of this type. Multiple Inheritance is supported.
- properties: any types, except Resource and its specialisation, includes a properties array [List]. Any [[#Property] is described by a set of attributes.
- version: the actual version of the type;
- changelog: the history of changes in the type representation. It is an object containing properties with version as key and the change description as values.
Property
Any Property is described by the following attributes:
- name*: the property name [String];
- type*: The Type of the Property (e.g. String, Integer, ...). See Property Type;
- description: the description of the property [String, default=null];
- mandatory: indicate if the property is mandatory or not [String, default=false];
- readOnly: the property cannot change its value [Boolean, default=false];
- notNull: whether the property must assume a value diverse from ’null’ or not [Boolean, default=false];
- max: whether the property can be limited to a maximum value [Integer, default=null];
- min: whether the property can be limited to a minimum value [Integer, default=null];
- regex: a regular expression to validate the property value [String, default=null]. A good online tool for regex is available at https://regex101.com/
Property Type Mapping
Property Type are mapped to and integer to be used in property definition:
Type binder is defined here: [1]
Type | Integer Mapping | Java type | Description |
---|---|---|---|
Boolean | 0 | java.lang.Boolean or boolean
|
Handles only the values True or False. |
Integer | 1 | java.lang.Integer or int or java.math.BigInteger
|
32-bit signed Integers. |
Short | 2 | java.lang.Short or short
|
Small 16-bit signed integers. |
Long | 3 | java.lang.Long or long
|
Big 64-bit signed integers. |
Float | 4 | java.lang.Float or float
|
Decimal numbers |
Double | 5 | java.lang.Double or double
|
Decimal numbers with high precision. |
Date | 6 | java.util.Date
|
Any date with the precision up to milliseconds. |
String | 7 | java.lang.String
|
Any string as alphanumeric sequence of chars. |
Binary | 8 | java.lang.Byte[] or byte[]
|
Can contain any value as byte array. |
Embedded | 9 | ? extends org.gcube.informationsystem.model.embedded.Embedded
|
This is an Object contained inside the owner Entity and has no Header. It is reachable only by navigating the owner Entity. |
Embedded list | 10 | List<? extends org.gcube.informationsystem.model.embedded.Embedded>
|
List of Objects contained inside the owner Entity and have no Header. They are reachable only by navigating the owner Entity. |
Embedded set | 11 | Set<? extends org.gcube.informationsystem.model.embedded.Embedded>
|
Set (no duplicates) of Objects contained inside the owner Entity and have no Header. They are reachable only by navigating the owner Entity. |
Embedded map | 12 | Map<String, ? extends org.gcube.informationsystem.model.embedded.Embedded>
|
Map of Objects contained inside the owner Entity and have no Header. They are reachable only by navigating the owner Entity. |
Byte | 17 | java.lang.Byte or byte
|
Single byte. usesful to store small 8-bit signed integers. |
Type Creation
PUT /resource-registry/schema/{ Type Name }
Description
Allow to create new Entity or Relation or Embedded Type.
Parameters
Name | Type | Required | Description |
---|---|---|---|
Type Name | String | true | The name of the new type to create |
Responses
Code | Type | Description |
---|---|---|
200 | String | The json representation of the newly created type (which is the same of the request) |
Examples
Resource Type Creation
PUT /resource-registry/schema/Actor
Request Body
{ "name":"Actor", "description":"Any entity (human or machine) playing an active role.", "abstractType":true, /* If the Resource cannot be instantiated */ "superclasses":["Resource"], /* Resource or any registered specialization. */ "properties":null /* MUST be null. The Resource cannot have any property. */ }
Facet Type Creation
PUT /resource-registry/schema/ContactFacet
Request Body
{ "name":"ContactFacet", "description":"This facet is expected to capture contact information", "abstractType": false, "superclasses":["Facet"], "properties":[ { "name":"name", "description":"First Name", "mandatory":true, "readonly":false, "notnull":true, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":null, "type":7 /* String*/ },{ "name":"eMail", "description": "A restricted range of RFC‑822 compliant email address. ... ", "mandatory":true, "readonly":false, "notnull":true, "max":null, "min":null, "regexpr":"^[a-z0-9._%+-]{1,128}@[a-z0-9.-]{1,128}$", "linkedType":null, "linkedClass":null, "type":7 /* String */ } ] }
IsRelatedTo Type Creation
PUT /resource-registry/schema/Hosts
Request Body
{ "name":"Hosts", "description": "…”, "abstractType":false, "superclasses":["IsRelatedTo"], "properties":[] }
ConsistsOf Type Creation
PUT /resource-registry/schema/HasContact
Request Body
{ "name":"HasContact", "description":"", "abstractType":true, "superclasses":["ConsistsOf"], "properties":[] }
Property Type Creation
PUT /resource-registry/schema/AccessPolicy
Request Body
{ "name":"AccessPolicy", "description":"", "abstractType":false, "superclasses":["Embedded"], "properties":[{ "name":"policy", "description":"", "mandatory":false, "readonly":false, "notnull":false, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":”ValueSchema”, "type": 9 /* Embedded */ },{ "name":"note", "description":"", "mandatory": false, "readonly":false, "notnull":false, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":null, "type":7 /* String */ }] }
Read Type Definition
GET /resource-registry/schema/{ Type Name }
Description
Allow to read Type Definition
Parameters
Name | Type | Required | Description |
---|---|---|---|
Type Name | String | true | The name of the type you want to retrieve the definition |
Responses
Code | Type | Description |
---|---|---|
200 | String | The json representation of the newly created type |
Examples
Resource Type
GET /resource-registry/schema/Actor
Response
{ "name":"Actor", "description":"Any entity (human or machine) playing an active role.", "abstractType":true, "superclasses":["Resource"], "properties":null }
Facet Type
GET /resource-registry/schema/ContactFacet
Response
{ "name":"ContactFacet", "description":"This facet is expected to capture contact information", "abstractType": false, "superclasses":["Facet"], "properties":[ { "name":"name", "description":"First Name", "mandatory":true, "readonly":false, "notnull":true, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":null, "type":7 /* String*/ },{ "name":"eMail", "description": "A restricted range of RFC‑822 compliant email address. ... ", "mandatory":true, "readonly":false, "notnull":true, "max":null, "min":null, "regexpr":"^[a-z0-9._%+-]{1,128}@[a-z0-9.-]{1,128}$", "linkedType":null, "linkedClass":null, "type":7 /* String */ } ] }
IsRelatedTo Type
GET /resource-registry/schema/Hosts
Response
{ "name":"Hosts", "description": "…”, "abstractType":false, "superclasses":["IsRelatedTo"], "properties":[] }
ConsistsOf Type
GET /resource-registry/schema/HasContact
Response
{ "name":"HasContact", "description":"", "abstractType":true, "superclasses":["ConsistsOf"], "properties":[] }
Property Type
GET /resource-registry/schema/AccessPolicy
Response
{ "name":"AccessPolicy", "description":"", "abstractType":false, "superclasses":["Embedded"], "properties":[{ "name":"policy", "description":"", "mandatory":false, "readonly":false, "notnull":false, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":”ValueSchema”, "type": 9 /* Embedded */ },{ "name":"note", "description":"", "mandatory": false, "readonly":false, "notnull":false, "max":null, "min":null, "regexpr":null, "linkedType":null, "linkedClass":null, "type":7 /* String */ }] }