---
# System prepended metadata

title: SOyA acquire

---

## Examples for `soya acquire`

1. simple "valid" example (new behaviour)
    Soya structure: [`ex1`](https://soya.ownyourdata.eu/ex1) (sorry, no YAML available yet)
    Input:
    ```json
    {
        "elements": ["a", "b"]
    }
    ```
    Command: `cat input.json | soya acquire ex1`
    Expected Output:
    ```json
    {
        "@context": {
            "@version": 1.1,
            "@vocab": "https://soya.ownyourdata.eu/ex1/"
        },
        "@graph": [{
            "@type": "ex1",
            "elements": {
                "@list": [
                    "a",
                    "b"
                ]
            }
        }]
    }
    ```
    Validation Command: `cat input.json | soya acquire ex1 | soya validate ex1`
    Notes:
    * based on the information in base ex1 that `elements` is a set -> the acquire functions should identify the array and replace it with `{"@list": [array]}`
    * the YAML for ex1 should look like
        ```yaml
        meta:
          name: ex1

        content:
          bases: 
            - name: ex1
              attributes: 
                elements: list<String>

          overlays: 
          - type: OverlayValidation
            base: ex1
            name: ex1ValidationOverlay
            attributes:
              elements:
                nodeKind: BlankNodeOrIRI        
        ```

2. simple "invalid" example (current behaviour)
    Soya structure: [`ex1`](https://soya.ownyourdata.eu/ex1)
    Input:
    ```json
    {
        "elements": "a"
    }
    ```
    Command: `cat input.json | soya acquire ex1`
    Expected Output:
    ```json
    {
      "@context": {
        "@version": 1.1,
        "@vocab": "https://soya.ownyourdata.eu/ex1/"
      },
      "@graph": [
        {
          "@type": "ex1",
          "elements": "a"
        }
      ]
    }
    ```
    Notes:
    * not sure if we should keep this behaviour -> might ask Fajar on the input

3. simple "invalid" example (current behaviour)
    Soya structure: [`ex1`](https://soya.ownyourdata.eu/ex1)
    Input:
    ```json
    {
        "elements": {"a": "b"}
    }
    ```
    Command: `cat input.json | soya acquire ex1`
    Expected Output:
    ```json
    {
      "@context": {
        "@version": 1.1,
        "@vocab": "https://soya.ownyourdata.eu/ex1/"
      },
      "@graph": [
        {
          "@type": "ex1",
          "elements": [
            {
              "@type": "rdf:List",
              "a": "b"
            }
          ]
        }
      ]
    }
    ```
    Notes:
    * not sure if we keep this behaviour -> might ask Fajar on the input
    * especially the behaviour of `"@type": "rdf:List"` is maybe strange

4. real world example (DID Document)
    Soya structure: [`Did`](https://soya.ownyourdata.eu/Did/yaml)
    Input:
    ```json
    {
      "@context": [
        "https://www.w3.org/ns/did/v1",
        "https://w3id.org/security/suites/ed25519-2020/v1"
      ],
      "id": "did:oyd:zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh",
      "verificationMethod": [
        {
          "id": "did:oyd:zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh#key-doc",
          "type": "Ed25519VerificationKey2020",
          "controller": "did:oyd:zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh",
          "publicKeyMultibase": "z6MusYB5iT5krCHYsZ76EzBaTdRwGKsaBhMcSbrXaPJgkuRQ"
        },
        {
          "id": "did:oyd:zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh#key-rev",
          "type": "Ed25519VerificationKey2020",
          "controller": "did:oyd:zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh",
          "publicKeyMultibase": "z6Mv7EYihbAat6Wq7GsjNsjcxt58dZT8fmsRjQGTkYamYrjB"
        }
      ],
      "keyAgreement":["did:oyd:zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh#key-doc"],
      "service": [
        {
          "id": "did:oyd:zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh#payload",
          "type": "Custom",
          "serviceEndpoint": "https://oydid.ownyourdata.eu",
          "payload": {
            "simple": "example"
          }
        }
      ]
    }
    ```
    Command: `cat did.jsonld | soya acquire Did`
    Expected Output:
    ```json
    {
        "@context": [
            "https://www.w3.org/ns/did/v1",
            "https://w3id.org/security/suites/ed25519-2020/v1"
        ],
        "id": "did:oyd:zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh",
        "verificationMethod": {
            "@list": [{
                    "id": "did:oyd:zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh#key-doc",
                    "type": "Ed25519VerificationKey2020",
                    "controller": "did:oyd:zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh",
                    "publicKeyMultibase": "z6MusYB5iT5krCHYsZ76EzBaTdRwGKsaBhMcSbrXaPJgkuRQ"
                },
                {
                    "id": "did:oyd:zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh#key-rev",
                    "type": "Ed25519VerificationKey2020",
                    "controller": "did:oyd:zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh",
                    "publicKeyMultibase": "z6Mv7EYihbAat6Wq7GsjNsjcxt58dZT8fmsRjQGTkYamYrjB"
                }
            ]
        },
        "keyAgreement": {
            "@list": ["did:oyd:zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh#key-doc"]
        },
        "service": {
            "@list": [{
                "id": "did:oyd:zQmaBZTghndXTgxNwfbdpVLWdFf6faYE4oeuN2zzXdQt1kh#payload",
                "type": "Custom",
                "serviceEndpoint": "https://oydid.ownyourdata.eu",
                "payload": {
                    "simple": "example"
                }
            }]
        }
    }
    ```
    Validation Command: not available yet but should be `cat did.jsonld | soya acquire Did | soya validate Did` with statements in the ValidationOverlay:
    ```yaml
    verificationMethod:
      nodeKind: BlankNodeOrIRI
    keyAgreement:
      nodeKind: BlankNodeOrIRI
    service:
      nodeKind: BlankNodeOrIRI
    ```
    Notes:
    * maybe also discuss with Fajar if we really want to allow JSON-LD input for `soya acquire` -> if not, let's just strip away `@context"`

## Working Example

SOyA Structure with Validation Overlay:
```jsonld=
{
  "@context": {
    "@version": 1.1,
    "@import": "https://ns.ownyourdata.eu/ns/soya-context.json",
    "@base": "https://soya.ownyourdata.eu/DidTmp/",
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "did": "https://www.w3.org/ns/did#"
  },
  "@graph": [{
      "@id": "DidTmp",
      "@type": "owl:Class",
      "subClassOf": "did:DIDSubject"
    },
    {
      "@id": "id",
      "@type": "owl:DatatypeProperty",
      "domain": "DidTmp",
      "range": "xsd:string"
    },
    {
      "@id": "verificationMethod",
      "@type": "owl:ObjectProperty",
      "domain": "DidTmp",
      "range": "http://www.w3.org/1999/02/22-rdf-syntax-ns#List"
    },
    {
      "@id": "VerificationMethod",
      "@type": "owl:Class",
      "subClassOf": "did:VerificationMethod"
    },
    {
      "@id": "id",
      "@type": "owl:DatatypeProperty",
      "domain": "VerificationMethod",
      "range": "xsd:string"
    },
    {
      "@id": "DidTmpOverlayValidation",
      "@type": "OverlayValidation",
      "onBase": "DidTmp",
      "name": "DidValidationOverlay",
      "sh:targetClass": "DidTmp",
      "sh:property": [{
          "sh:path": "id",
          "sh:minCount": 1,
          "sh:maxCount": 1,
          "sh:pattern": "^did:[a-z0-9]+:[a-zA-Z0-9.:\\-_%]+$",
          "sh:message": "there must be one valid 'id' in a DID document"
        },
        {
          "sh:path": "verificationMethod",
          "sh:minCount": 1,
          "sh:maxCount": 1,
          "sh:property": [{
            "sh:path": ["http://www.w3.org/ns/shacl#zeroOrMorePath", "http://www.w3.org/1999/02/22-rdf-syntax-ns#rest"],
            "sh:property": [{
              "sh:path": "http://www.w3.org/1999/02/22-rdf-syntax-ns#first",
              "sh:property": [{
                  "sh:path": "id",
                  "sh:minCount": 1,
                  "sh:maxCount": 1
                },
                {
                  "sh:path": "type",
                  "sh:minCount": 1,
                  "sh:maxCount": 1
                }
              ]
            }]
          }]
        }
      ]
    }
  ]
}
```

Test JSON-LD:
```jsonld
{
  "@context": {
    "@version": 1.1,
    "did": "https://soya.ownyourdata.eu/DidTmp/",
    "@vocab": "https://soya.ownyourdata.eu/DidTmp/"
  },
  "@graph": [{
    "@type": "DidTmp",
    "id": "did:oyd:zQmaaUbj3kfbFk2LjE9PPnXy8sbuMBbMWvh6pm4Vr2wVkzr",
    "verificationMethod": {
      "@list": [{
        "id": "did:oyd:zQmaaUbj3kfbFk2LjE9PPnXy8sbuMBbMWvh6pm4Vr2wVkzr#key-doc",
        "type": "Ed25519VerificationKey2020",
        "controller": "did:oyd:zQmaaUbj3kfbFk2LjE9PPnXy8sbuMBbMWvh6pm4Vr2wVkzr",
        "publicKeyMultibase": "z6MuwvdHwfVBCy6WDhPzBtDEds6fSFJEMtM5hmhEWdWJ5P46"
      }]
    }
  }]
}
```

Command: `echo did.jsonld | soya validate DidTmp`