DocID json-schema definition about cips HOT 14 OPEN

This seems pretty great!

Thanks!

Maybe naming the CIP DocID json-schema definition or something similar that inlcudes json-schmea would be more clear?

Yes good idea 👍

Why would we want to include multiple schemas in one reference? Would it not be better to have multiple definitions for each schema to decrease ambiguity?

At build time it's used to identify possible schemas the document could use, but it's not necessarily restricted to a single one.
For example we can have a media feed document that has items that can be of different types (image, audio or video) so at built time we can discover that we need to be aware of the image, audio and video schemas, but at runtime the loaded document will specify its schema anyways so we can have the runtime logic work accordingly.
The main use case here is similar to the GraphQL union type.

I think the example would be more clear if you used a named definition!

Sorry I'm not sure what you mean by named definition here?

from cips.

No blocker, I opened a PR for it that references this issue for discussions: #86

from cips.

@oed I created #88 and opened a PR to update CIP-82 with these changes in #89, I think that would nicely work around this issue.

from cips.

This seems pretty great!

A few questions:

Maybe naming the CIP DocID json-schema definition or something similar that inlcudes json-schmea would be more clear?

Why would we want to include multiple schemas in one reference? Would it not be better to have multiple definitions for each schema to decrease ambiguity?

I think the example would be more clear if you used a named definition!

from cips.

Like so:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "IDXKeychain",
  "properties": {
    "notes": {
      "type": "array",
      "items": { "$ref": "#/definitions/DocID" }
    }
  },
  "additionalProperties": false,
  "required": [ "notes" ],
  "definitions": {
    "DocID": {
      "type": "string",
      "$id": "ceramic://doc",
      "$ceramicSchema": "<schema docID>",
      "maxLength": 150,
    }
  }
}

I think this makes it a bit clearer for someone who is trying to understand what this is :)

Also would be helpful to have an example with an actual Schema DocID!

from cips.

I don't think it makes much sense to use the definitions here because using $ceramicSchema makes the field specific to a given schema rather than generic to any document, so in this case this would be simpler:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "notes": {
      "type": "array",
      "items": {
        "type": "string",
        "$id": "ceramic://doc",
        "$ceramicSchema": "<schema docID>",
        "maxLength": 150
      }
    }
  },
  "additionalProperties": false,
  "required": ["notes"]
}

from cips.

Yeah, that's simpler. I more meant that it would be easier to understand for someone reading this CIP because it clearly separates what is part of the DocID reference.

from cips.

I see, thanks! I updated the example.

from cips.

'<Note schema docID>' should be '<Note schema commitID>' right?

from cips.

I should accept either, maybe we can name it docRef then as per Sergey's PR?

from cips.

Schemas always have to be a CommitID afaik.

edit: disregard my misunderstanding :)

from cips.

@PaulLeCam Any blockers for making a PR for this CIP?

from cips.

I'm seeing an issue if I have multiple docids in the same schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "ConvictionState",
  "properties": {
    "context": {
      "type": "string"
    },
    "supply": {
      "type": "number"
    },
    "participants": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/participants"
      }
    },
    "proposals": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/proposals"
      }
    }
  },
  "additionalProperties": false,
  "required": [
    "context",
    "supply",
    "participants",
    "proposals"
  ],
  "definitions": {
    "participants": {
      "type": "object",
      "properties": {
        "account": {
          "type": "string"
        },
        "balance": {
          "type": "number"
        },
        "convictions": {
          "type": "string",
          "$id": "ceramic://doc",
          "$ceramicSchema": "<Convictions commitid>",
          "maxLength": 150
        }
      },
      "required": [
        "account",
        "balance",
        "convictions"
      ]
    },
    "proposals": {
      "type": "object",
      "properties": {
        "proposal": {
          "type": "string",
          "$id": "ceramic://doc",
          "$ceramicSchema": "<Proposal docid>",
          "maxLength": 150
        },
        "totalConviction": {
          "type": "number"
        },
        "triggered": {
          "type": "boolean"
        }
      },
      "required": [
        "proposal",
        "totalConviction",
        "triggered"
      ]
    }
  }
}

At https://www.jsonschemavalidator.net/ I see this error:

from cips.

Seems like we can't use $id as I intended then, thanks for reporting this, I'll look for alternative options.

from cips.