Define RDF/JSON-LD metadata standards for gov & groups

[aaronc]

The gov and group module have a metadata field for proposals (and other elements) that we want to define JSON-LD standards for.

The basic idea of how the metadata field should be used is that either it should contain a small amount of inline JSON-LD or contain a URL which de-references to some JSON-LD.

We should describe some basic standards for this JSON-LD which define the standardized IRIs to describe basic things like:

• title
• description
• forumUrl

Likely we should reuse existing IRIs from existing projects like schema.org or Dublin Core where possible.

As artifacts of this work we probably want:

• high-level documentation with examples
• a reusable JSON-LD context probably served under some cosmos.network URL
• SHACL shapes graphs for validation &/or OWL ontologies (nice-to-have)

Such documents can be stored in the SDK but should be served from stable URLs, probably under cosmos.network

Note that this can be done after the 0.46 release and is not blocking.

[thelastjosh]

👋 coming here on Sam Hart's recommendation. A group of us are just getting started on a multi-chain standard for DAOs after releasing EIP-4824 at daostar.one/EIP. Maybe relevant for this issue?

[hxrts]

linking the following issues so we don't forget

#10932
#11268

[LexaMichaelides]

Proposed structure for the JSON referenced by the metadata field (syntax prob not great...it's my first time).
The thinking being that the least a proposal needs to be legible on an explorer, bot, or other tooling is a title and summary but we also want people to be thinking about what it means to vote yes/no/etc on a particular proposal. Those vote meanings could be used on a voting UI as well.

Edited to add subfield for vote meanings.

{
 "@context": "",
  "title": "",
  "authors": "",
  "summary": "",
  "details": "",
  "forumURL": "",
  “votes”:
        {    
          "yesMeaning": "",
          "noMeaning": "",
          "vetoMeaning": "",
          "abstainMeaning": "",
        },

  "required": ["title","summary","votes"]
}

[thelastjosh]

Brief comment since I don’t have all the appropriate context here, but in general proposals are going to have lots of different potential options/choices. You may want to define a proposal type for generic yes/no abstain etc. Generically there are different types of proposals re: binding on chain execution, binding off chain execution, and non-binding execution (on-chain signaling), and any variety of off-chain proposals.

[hxrts]

the proposal type should be queryable on-chain so not sure it makes sense to have that data redundantly here if it opens the door to mismatches.

[nooomski]

Some conclusions from the last gov/groups call:

1. Let's not use JSON-LD, for now. This adds complexity to the clients who will need to implement a JSON-LD interpreter instead of simply parsing regular JSON. We can reconsider if clear use cases arise.
2. The votes field and their individual meanings potentially don't apply to future decision policy types with different voting options. We should use a single field instead, perhaps voteMeaning?
3. We also need a metadata schema for a Group, a Group Policy and for a Vote. For groups we suggested:

{
  "name": "",
  "description": "",
  "groupURL": "",
  "groupForumURL": "",
}

For decision policies we didn't decide whether to include a description or not:

{
  "name": "",
  "description": "",
}

If we do not include a description, the benefit is that we could try to suggest limiting the metadata to the default 255 characters (set as a param) and keep this data on-chain instead of off-chain on IPFS as is currently what we're planning to recommend for gov & group proposals and group metadata.

For individual Votes I suggest we keep a very simple schema (if any), and keep this on-chain, again limited to 255 characters.

{
  "reason": "",
}

And lastly, do we need to define the schema like this? https://json-schema.org/learn/getting-started-step-by-step.html

[hxrts]

would make the following changes:

vote metadata field from "reason" -> "justification"

and this is what I would use for the proposal metadata

{
  "title": "",
  "authors": "",
  "summary": "",
  "details": "",
  "forumURL": "",
  “voteOptionContext”: "",
}

[robert-zaremba]

@nooomski , so you don't want that groupURL will reference to a JSON document? I think we should require it from start, and keep a minimum amount of data on chain.

[hxrts]

groupURL refers to the group's regular website

[robert-zaremba]

It could be groupURL -> metadata JSON.website -> regular website.

[hxrts]

I was imagining all these things were json blobs linked by IPFS content addresses

[nooomski]

groupURL was just meant to be a link to the website. Maybe the naming is confusing. Perhaps we should just use groupWebsite.

[hxrts]

Proposal (both gov and group)

off-chain

{
  "title": "",
  "authors": "",
  "summary": "",
  "details": "",
  "proposalForumURL": "",
  "voteOptionContext": "",
}

Group

off-chain

{
  "name": "",
  "description": "",
  "groupWebsiteURL": "",
  "groupForumURL": "",
}

Decision policy

on-chain 255 character default
note: we debated whether to include description and whether that would force us to use an off-chain resource. I'd say let's keep it and people will just be forced to keep name and description pretty concise.

{
  "name": "",
  "description": "",
}

Vote (both gov and group)

on-chain 255 character default

{
  "justification": "",
}

[hxrts]

ok I think the metadata above is good to go. where's the best place to add to the documentation? I can make a PR for that.

[amaury1093]

Maybe in a new .md file in https://github.com/cosmos/cosmos-sdk/tree/main/x/group/spec? This way it will also show up on docs.cosmos.network

[hxrts]

There are items that refer to gov module metadata as well. Should I make 2 files, the other in the equivalent gov module location?

[amaury1093]

Yes, that could work. Maybe the gov one can link to the group one (or vice versa, whichever you prefer) for the shared spec.