feat: refactor identifiers + document naming conventions

README.md

@@ -41,6 +41,20 @@ It allows you to work with Resources and their collection of attributes.
 * Open Policy Agent
 * SAML2
 
+## Naming conventions:
+
+* All identifiers are prefixed with a FQDN (Fully Qualified Domain Name). I.e. `core.xillion.cloud/display-name`
+* The identifier FQDN is owned by the entity that defines the identifier (i.e. do not randomly defined resource or attribute identifiers with domain names that you do not own).
+* Attribute identifiers do not specify a scheme (i.e. `http://`, `https://`, `file://` etc)
+* Attribute identifiers do not contain a path prefix (i.e. do not prefix paths with `/xillion` etc)
+* Identifiers are lower-case only, and allow dashes for word-spacing (i.e. `/display-name`)
+* Any level of sub-paths is allowed in identifiers. The recommendation is to keep the levels to a minimum (i.e `x.example.web/a/b/c/d/e/f is allowed but discouraged)
+* Profile identifiers are in a sub-path prefixed with `/profiles`.
+* Data-type identifiers are in a sub-path prefixed with `/data-types`.
+* Attribute identifiers do not use a prefix. (i.e. do not use prefix `/attributes`)
+* Resource identifiers do not use a prefix. (i.e. do not use prefix `/resources`)
+* Packages (FQDN) define either a set of attributes and profiles (library) -or- resources (content), not both.
+
 ## License
 
 MIT. Please refer to the [license file](LICENSE) for details.

assets/core.xillion.cloud.yaml

@@ -1,106 +1,106 @@
 resources:
   # ========= [ DATA TYPES ] =========
-  http://www.w3.org/2001/XMLSchema#string:
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/attributes/data-type
-    https://core.xillion.cloud/xillion/attributes/alias: string
-    https://core.xillion.cloud/xillion/attributes/php-validator-class: Xillion\Core\DataType\Xml\StringType
-    https://core.xillion.cloud/xillion/attributes/description: Regular string
+  core.xillion.cloud/data-types/string:
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/data-type
+    core.xillion.cloud/display-name: string
+    core.xillion.cloud/php-validator-class: Xillion\Core\DataType\Xml\StringType
+    core.xillion.cloud/description: Regular string
 
-  http://www.w3.org/2001/XMLSchema#integer:
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/attributes/data-type
-    https://core.xillion.cloud/xillion/attributes/alias: integer
-    https://core.xillion.cloud/xillion/attributes/php-validator-class: Xillion\Core\DataType\Xml\IntegerType
-    https://core.xillion.cloud/xillion/attributes/description: Regular integer
+  core.xillion.cloud/data-types/integer:
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/data-type
+    core.xillion.cloud/display-name: integer
+    core.xillion.cloud/php-validator-class: Xillion\Core\DataType\Xml\IntegerType
+    core.xillion.cloud/description: Regular integer
 
-  https://core.xillion.cloud/xillion/data-types/resource:
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/attributes/data-type
-    https://core.xillion.cloud/xillion/attributes/alias: Resource
-    https://core.xillion.cloud/xillion/attributes/php-validator-class: Xillion\Core\DataType\ResourceType
-    https://core.xillion.cloud/xillion/attributes/description: Link to another Resource
+  core.xillion.cloud/data-types/resource:
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/data-type
+    core.xillion.cloud/display-name: Resource
+    core.xillion.cloud/php-validator-class: Xillion\Core\DataType\ResourceType
+    core.xillion.cloud/description: Link to another Resource
 
   # ========= [ ATTRIBUTES ] =========
-  https://core.xillion.cloud/xillion/attributes/data-type:
-    https://core.xillion.cloud/xillion/attributes/alias: Data type
-    https://core.xillion.cloud/xillion/attributes/data-type: http://www.w3.org/2001/XMLSchema#string
-    https://core.xillion.cloud/xillion/attributes/description: Data type the values validate against
+  core.xillion.cloud/data-type:
+    core.xillion.cloud/display-name: Data type
+    core.xillion.cloud/data-type: core.xillion.cloud/data-types/string
+    core.xillion.cloud/description: Data type the values validate against
 
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/profiles/attribute
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/profiles/attribute
 
-  https://core.xillion.cloud/xillion/attributes/is-array:
-    https://core.xillion.cloud/xillion/attributes/alias: Is array?
-    https://core.xillion.cloud/xillion/attributes/data-type: http://www.w3.org/2001/XMLSchema#string
-    https://core.xillion.cloud/xillion/attributes/description: Is this value an array?
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/profiles/attribute
+  core.xillion.cloud/is-array:
+    core.xillion.cloud/display-name: Is array?
+    core.xillion.cloud/data-type: core.xillion.cloud/data-types/string
+    core.xillion.cloud/description: Is this value an array?
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/profiles/attribute
 
-  https://core.xillion.cloud/xillion/attributes/profiles:
-    https://core.xillion.cloud/xillion/attributes/alias: Profiles
-    https://core.xillion.cloud/xillion/attributes/data-type: http://www.w3.org/2001/XMLSchema#string
-    https://core.xillion.cloud/xillion/attributes/is-array: true
-    https://core.xillion.cloud/xillion/attributes/description: Array of profiles this resource conforms to
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/profiles/attribute
+  core.xillion.cloud/profiles:
+    core.xillion.cloud/display-name: Profiles
+    core.xillion.cloud/data-type: core.xillion.cloud/data-types/string
+    core.xillion.cloud/is-array: true
+    core.xillion.cloud/description: Array of profiles this resource conforms to
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/profiles/attribute
 
-  https://core.xillion.cloud/xillion/attributes/description:
-    https://core.xillion.cloud/xillion/attributes/alias: Description
-    https://core.xillion.cloud/xillion/attributes/data-type: http://www.w3.org/2001/XMLSchema#string
-    https://core.xillion.cloud/xillion/attributes/description: Human friendly resource description
-    https://core.xillion.cloud/xillion/attributes/is-array: false
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/profiles/attribute
+  core.xillion.cloud/description:
+    core.xillion.cloud/display-name: Description
+    core.xillion.cloud/data-type: core.xillion.cloud/data-types/string
+    core.xillion.cloud/description: Human friendly resource description
+    core.xillion.cloud/is-array: false
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/profiles/attribute
 
-  https://core.xillion.cloud/xillion/attributes/required-attributes:
-    https://core.xillion.cloud/xillion/attributes/alias: Required attributes
-    https://core.xillion.cloud/xillion/attributes/data-type: http://www.w3.org/2001/XMLSchema#string
-    https://core.xillion.cloud/xillion/attributes/is-array: true
-    https://core.xillion.cloud/xillion/attributes/description: Lists attributes required by a resource that implements a resource type
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/profiles/attribute
+  core.xillion.cloud/required-attributes:
+    core.xillion.cloud/display-name: Required attributes
+    core.xillion.cloud/data-type: core.xillion.cloud/data-types/string
+    core.xillion.cloud/is-array: true
+    core.xillion.cloud/description: Lists attributes required by a resource that implements a resource type
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/profiles/attribute
 
-  https://core.xillion.cloud/xillion/attributes/php-validator-class:
-    https://core.xillion.cloud/xillion/attributes/alias: PHP Class
-    https://core.xillion.cloud/xillion/attributes/data-type: http://www.w3.org/2001/XMLSchema#string
-    https://core.xillion.cloud/xillion/attributes/description: PHP Class that implements this resource
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/profiles/attribute
+  core.xillion.cloud/php-validator-class:
+    core.xillion.cloud/display-name: PHP Class
+    core.xillion.cloud/data-type: core.xillion.cloud/data-types/string
+    core.xillion.cloud/description: PHP Class that implements this resource
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/profiles/attribute
 
-  https://core.xillion.cloud/xillion/attributes/alias:
-    https://core.xillion.cloud/xillion/attributes/alias: Alias
-    https://core.xillion.cloud/xillion/attributes/data-type: http://www.w3.org/2001/XMLSchema#string
-    https://core.xillion.cloud/xillion/attributes/description: User-friendly display name for this resource
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/profiles/attribute
+  core.xillion.cloud/display-name:
+    core.xillion.cloud/display-name: Alias
+    core.xillion.cloud/data-type: core.xillion.cloud/data-types/string
+    core.xillion.cloud/description: User-friendly display name for this resource
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/profiles/attribute
 
   # ========= [ PROFILES ] =========
 
   # Xillion core profiles
-  https://core.xillion.cloud/xillion/profiles/data-type:
-    https://core.xillion.cloud/xillion/attributes/alias: Data-type
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/profiles/profile
-    https://core.xillion.cloud/xillion/attributes/description: Defines a data type
+  core.xillion.cloud/profiles/data-type:
+    core.xillion.cloud/display-name: Data-type
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/profiles/profile
+    core.xillion.cloud/description: Defines a data type
 
-  https://core.xillion.cloud/xillion/profiles/profile:
-    https://core.xillion.cloud/xillion/attributes/alias: Profile
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/profiles/profile
-    https://core.xillion.cloud/xillion/attributes/description: Defines a profile
+  core.xillion.cloud/profiles/profile:
+    core.xillion.cloud/display-name: Profile
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/profiles/profile
+    core.xillion.cloud/description: Defines a profile
 
-  https://core.xillion.cloud/xillion/profiles/attribute:
-    https://core.xillion.cloud/xillion/attributes/alias: Attribute
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/profiles/profile
-    https://core.xillion.cloud/xillion/attributes/description: Defines an attribute
-    https://core.xillion.cloud/xillion/attributes/required-attributes:
-      - https://core.xillion.cloud/xillion/attributes/data-type
-      - https://core.xillion.cloud/xillion/attributes/description
+  core.xillion.cloud/profiles/attribute:
+    core.xillion.cloud/display-name: Attribute
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/profiles/profile
+    core.xillion.cloud/description: Defines an attribute
+    core.xillion.cloud/required-attributes:
+      - core.xillion.cloud/data-type
+      - core.xillion.cloud/description
 
-  https://core.xillion.cloud/xillion/profiles/container:
-    https://core.xillion.cloud/xillion/attributes/alias: Container
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/profiles/profile
-    https://core.xillion.cloud/xillion/attributes/description: Contains other resources as part of a hierarchy
+  core.xillion.cloud/profiles/container:
+    core.xillion.cloud/display-name: Container
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/profiles/profile
+    core.xillion.cloud/description: Contains other resources as part of a hierarchy

assets/xacml-10.xillion.cloud.yaml

@@ -1,32 +1,32 @@
 resources:
   # ========= [ ATTRIBUTES ] =========
   urn:oasis:names:tc:xacml:1.0:subject:subject-id:
-    https://core.xillion.cloud/xillion/attributes/alias: Subject
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/profiles/attribute
-    https://core.xillion.cloud/xillion/attributes/data-type: http://www.w3.org/2001/XMLSchema#string
-    https://core.xillion.cloud/xillion/attributes/description: Is the name of the user as required by Health Insurance Portability and Accountability Act (HIPAA) Privacy Disclosure Accounting. The name will be typed as a string and in plain text.
+    core.xillion.cloud/display-name: Subject
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/xillion/profiles/attribute
+    core.xillion.cloud/data-type: core.xillion.cloud/data-types/string
+    core.xillion.cloud/description: Is the name of the user as required by Health Insurance Portability and Accountability Act (HIPAA) Privacy Disclosure Accounting. The name will be typed as a string and in plain text.
   urn:oasis:names:tc:xacml:1.0:subject:group:
-    https://core.xillion.cloud/xillion/attributes/alias: Group
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/profiles/attribute
-    https://core.xillion.cloud/xillion/attributes/data-type: http://www.w3.org/2001/XMLSchema#string
-    https://core.xillion.cloud/xillion/attributes/description: User group(s).
+    core.xillion.cloud/display-name: Group
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/xillion/profiles/attribute
+    core.xillion.cloud/data-type: core.xillion.cloud/data-types/string
+    core.xillion.cloud/description: User group(s).
   urn:oasis:names:tc:xacml:1.0:resource:resource-id:
-    https://core.xillion.cloud/xillion/attributes/alias: Resource ID
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/profiles/attribute
-    https://core.xillion.cloud/xillion/attributes/data-type: http://www.w3.org/2001/XMLSchema#string
-    https://core.xillion.cloud/xillion/attributes/description: Unique identifier of the resource defined by and controlled by the servicing organization. In healthcare this is the patient unique identifier.
+    core.xillion.cloud/display-name: Resource ID
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/xillion/profiles/attribute
+    core.xillion.cloud/data-type: core.xillion.cloud/data-types/string
+    core.xillion.cloud/description: Unique identifier of the resource defined by and controlled by the servicing organization. In healthcare this is the patient unique identifier.
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname:
-    https://core.xillion.cloud/xillion/attributes/alias: Given name
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/profiles/attribute
-    https://core.xillion.cloud/xillion/attributes/data-type: http://www.w3.org/2001/XMLSchema#string
-    https://core.xillion.cloud/xillion/attributes/description: Given name of this person
+    core.xillion.cloud/display-name: Given name
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/xillion/profiles/attribute
+    core.xillion.cloud/data-type: core.xillion.cloud/data-types/string
+    core.xillion.cloud/description: Given name of this person
   http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress:
-    https://core.xillion.cloud/xillion/attributes/alias: Email address
-    https://core.xillion.cloud/xillion/attributes/profiles:
-      - https://core.xillion.cloud/xillion/profiles/attribute
-    https://core.xillion.cloud/xillion/attributes/data-type: http://www.w3.org/2001/XMLSchema#string
-    https://core.xillion.cloud/xillion/attributes/description: Email address
+    core.xillion.cloud/display-name: Email address
+    core.xillion.cloud/profiles:
+      - core.xillion.cloud/xillion/profiles/attribute
+    core.xillion.cloud/data-type: core.xillion.cloud/data-types/string
+    core.xillion.cloud/description: Email address

example/Entity/User.php

@@ -23,13 +23,13 @@ public function getResourceConfig(): array
     {
         return [
             '$id' => $this->id,
-            'https://core.xillion.cloud/xillion/attributes/alias' => $this->id,
-            'https://core.xillion.cloud/xillion/attributes/profiles' => [
-                'https://example.linkorb.com/xillion/profiles/user',
+            'core.xillion.cloud/display-name' => $this->id,
+            'core.xillion.cloud/profiles' => [
+                'example.linkorb.com/profiles/user',
             ],
             'urn:oasis:names:tc:xacml:1.0:subject:subject-id' => $this->id,
-            'https://example.linkorb.com/xillion/attributes/ubid' => $this->id,
-            'https://example.linkorb.com/xillion/attributes/user-groups' => $this->groupNames,
+            'example.linkorb.com/ubid' => $this->id,
+            'example.linkorb.com/user-groups' => $this->groupNames,
             'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname' => $this->displayName,
             'http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress' => $this->email,
         ];

example/ResourceProvider/ProjectResourceProvider.php

@@ -20,7 +20,7 @@ public function getResourceConfig($obj): array
         return [
             '$id' => $obj->getId(),
             'urn:oasis:names:tc:xacml:1.0:resource:resource-id' => $obj->getId(),
-            'https://example.linkorb.com/xillion/attributes/user-groups' => $obj->getGroupNames(),
+            'example.linkorb.com/user-groups' => $obj->getGroupNames(),
         ];
     }
 }