A work-in-progress proposal for schema features in the Hypermedia protocol

Problem

Onyx is highly pragmatic- we are not introducing formality for the sake of it.

We aim to solve the following problems:

Hypermedia Protocol Schemas

Problems Design Constraints Solution Notes and References

Hypermedia Protocol Schemas

Problems Design Constraints Solution Notes and References

Hypermedia Protocol Schemas

Problems Design Constraints Solution Notes and References

Hypermedia Protocol Schemas

Problems Design Constraints Solution Notes and References

Solution

Before we implement schemas, we must decide how to balance Open World Assumption and Closed World Assumption. Also, we must support existing data in the HM network which does not yet have a schema. The other goal is to keep the barrier low for new implementers of software on the network.

So, schemas are optional. HM is "Open World" by default. We include fallback schemas for existing types in HM25. A schema provides utility but is not meant to break software. At the most extreme, software will warn users when content does not conform to the stated schema.

What are the hard requirements for data in the HM ecosystem? All HM content must:

Be parsable. We are using DAG-CBOR encoded IPFS blobs. If this parsing fails, the data is considered garbage. Otherwise, we can present it to the user in some capacity.
Have correct signature, trust, capabilities - All software in the HM ecosystem must build upon our trust primitives to ensure that data is owned and controlled by the correct keys. This is a prerequisite of Onyx Hypermedia

Note: it is important for users to see what data exists inside the content they are referencing and signing. If the software encounters unknown fields in the data, they must be presented to the user in the best way possible. This will prevent users from accidentally referencing and signing "invisible" content which may be undesirable or weighty. Unexpected data that shows up in any blob (Profiles, Changes, Refs, Doc Change Blocks) must be surfaced to the user.

Schema Definitions

Still undecided. See below "Schema Decision-Making"

Fallback Schemas

To handle existing content, we will resolve to our own published schemas depending on the "type" field that is defined.

New content signed by respectful software will include the appropriate schema metadata.

Schema Decision-Making

A work in progress

Inspirations and References

Assorted technology we considered, much that helped inspire/influence this proposal

RDF
- RDFS
- OWL
- SHACL + DASH
- SKOS
XRPC
graphQL
IPLD schemas
XSL (XML Schemas)
FHIR

","enableWebSigning","https://ifebitcoin.org","origin","homeMetadata",{"_332":1574,"_646":1575,"_1556":1576,"_647":1570,"_1558":47,"_1559":1577,"_1578":1579,"_1157":8,"_649":8,"_775":776,"_1560":1580},"Instituto de Filosofía y Economía Bitcoin","ipfs://bafkreidefxplum2mkfvv2uhaupvil5uvbguud5s2p7dgyp6orchw4f6jpm","ipfs://bafkreifsdwjltm7dcv2a6vlnae6wy37ep2f4wgxo2hfjk4cn3sgkuvnake","ipfs://bafkreibpra4x7f5yuyijo7erlpbpahsmtaeoargic3dyda2ccwdxfyafle","seedExperimentalHomeOrder","CreatedFirst",{"_1562":1581},"Center","originHomeId",{"_349":1584,"_36":1585,"_325":1586,"_319":-5,"_351":-5,"_352":-5,"_353":-5,"_354":-5},"z6MkmoafLuwBs51a18PfEqjmBmXE2idHPLAdsCqm7VjQHFCs","hm://z6MkmoafLuwBs51a18PfEqjmBmXE2idHPLAdsCqm7VjQHFCs",[],"meta",{"_1589":1590,"_1834":1835},"values",{"_1591":1592,"_1594":1595,"_1596":1597,"_1598":1599,"_1601":1602,"_1603":1604,"_1605":1606,"_1608":1609,"_1610":1611,"_1612":1613,"_1614":1615,"_1616":1617,"_1618":1619,"_1620":1621,"_1622":1623,"_1624":1625,"_1626":1627,"_1628":1629,"_1630":1631,"_1632":1633,"_1634":1635,"_1636":1637,"_1638":1639,"_1640":1641,"_1642":1643,"_1644":1645,"_1646":1647,"_1648":1649,"_1650":1651,"_1652":1653,"_1654":1655,"_1656":1657,"_1658":1659,"_1660":1661,"_1662":1663,"_1664":1665,"_1666":1667,"_1668":1669,"_1670":1671,"_1672":1673,"_1674":1675,"_1676":1677,"_1678":1679,"_1680":1681,"_1682":1683,"_1684":1685,"_1686":1687,"_1688":1689,"_1690":1691,"_1692":1693,"_1694":1695,"_1696":1697,"_1698":1699,"_1700":1701,"_1702":1703,"_1704":1705,"_1706":1707,"_1708":1709,"_1710":1711,"_1712":1713,"_1714":1715,"_1716":1717,"_1718":1719,"_1720":1721,"_1722":1723,"_1724":1725,"_1726":1727,"_1728":1729,"_1730":1731,"_1732":1733,"_1734":1735,"_1736":1737,"_1738":1739,"_1740":1741,"_1742":1743,"_1744":1745,"_1746":1747,"_1748":1749,"_1750":1751,"_1752":1753,"_1754":1755,"_1756":1757,"_1758":1759,"_1760":1761,"_1762":1763,"_1764":1765,"_1766":1767,"_1768":1769,"_1770":1771,"_1772":1773,"_1774":1775,"_1776":1777,"_1778":1779,"_1780":1781,"_1782":1783,"_1784":1785,"_1786":1787,"_1788":1789,"_1790":1791,"_1792":1793,"_1794":1795,"_1796":1797,"_1798":1799,"_1800":1801,"_1802":1803,"_1804":1805,"_1806":1807,"_1808":1809,"_1810":1811,"_1812":1813,"_1814":1815,"_1816":1817,"_1818":1819,"_1820":1821,"_1822":1823,"_1824":1825,"_1826":1827,"_1828":1829,"_1830":1831,"_1832":1833},"document.generationInfo.generation",[1593],"bigint","dehydratedState.queries.0.state.data.document.generationInfo.generation",[1593],"dehydratedState.queries.1.state.data.document.generationInfo.generation",[1593],"dehydratedState.queries.1.queryKey.2",[1600],"undefined","dehydratedState.queries.2.state.data.0.createTime.seconds",[1593],"dehydratedState.queries.2.state.data.0.updateTime.seconds",[1593],"dehydratedState.queries.2.state.data.0.sortTime",[1607],"Date","dehydratedState.queries.2.state.data.0.activitySummary.latestCommentTime.seconds",[1593],"dehydratedState.queries.2.state.data.0.activitySummary.latestChangeTime.seconds",[1593],"dehydratedState.queries.2.state.data.0.generationInfo.generation",[1593],"dehydratedState.queries.2.state.data.0.redirectInfo",[1600],"dehydratedState.queries.2.state.data.1.createTime.seconds",[1593],"dehydratedState.queries.2.state.data.1.updateTime.seconds",[1593],"dehydratedState.queries.2.state.data.1.sortTime",[1607],"dehydratedState.queries.2.state.data.1.activitySummary.latestCommentTime.seconds",[1593],"dehydratedState.queries.2.state.data.1.activitySummary.latestChangeTime.seconds",[1593],"dehydratedState.queries.2.state.data.1.generationInfo.generation",[1593],"dehydratedState.queries.2.state.data.1.redirectInfo",[1600],"dehydratedState.queries.2.state.data.2.createTime.seconds",[1593],"dehydratedState.queries.2.state.data.2.updateTime.seconds",[1593],"dehydratedState.queries.2.state.data.2.sortTime",[1607],"dehydratedState.queries.2.state.data.2.activitySummary.latestCommentTime.seconds",[1593],"dehydratedState.queries.2.state.data.2.activitySummary.latestChangeTime.seconds",[1593],"dehydratedState.queries.2.state.data.2.generationInfo.generation",[1593],"dehydratedState.queries.2.state.data.2.redirectInfo",[1600],"dehydratedState.queries.2.state.data.3.createTime.seconds",[1593],"dehydratedState.queries.2.state.data.3.updateTime.seconds",[1593],"dehydratedState.queries.2.state.data.3.sortTime",[1607],"dehydratedState.queries.2.state.data.3.activitySummary.latestCommentTime.seconds",[1593],"dehydratedState.queries.2.state.data.3.activitySummary.latestChangeTime.seconds",[1593],"dehydratedState.queries.2.state.data.3.generationInfo.generation",[1593],"dehydratedState.queries.2.state.data.3.redirectInfo",[1600],"dehydratedState.queries.2.state.data.4.createTime.seconds",[1593],"dehydratedState.queries.2.state.data.4.updateTime.seconds",[1593],"dehydratedState.queries.2.state.data.4.sortTime",[1607],"dehydratedState.queries.2.state.data.4.activitySummary.latestCommentTime.seconds",[1593],"dehydratedState.queries.2.state.data.4.activitySummary.latestChangeTime.seconds",[1593],"dehydratedState.queries.2.state.data.4.generationInfo.generation",[1593],"dehydratedState.queries.2.state.data.4.redirectInfo",[1600],"dehydratedState.queries.2.state.data.5.createTime.seconds",[1593],"dehydratedState.queries.2.state.data.5.updateTime.seconds",[1593],"dehydratedState.queries.2.state.data.5.sortTime",[1607],"dehydratedState.queries.2.state.data.5.activitySummary.latestCommentTime.seconds",[1593],"dehydratedState.queries.2.state.data.5.activitySummary.latestChangeTime.seconds",[1593],"dehydratedState.queries.2.state.data.5.generationInfo.generation",[1593],"dehydratedState.queries.2.state.data.5.redirectInfo",[1600],"dehydratedState.queries.2.state.data.6.createTime.seconds",[1593],"dehydratedState.queries.2.state.data.6.updateTime.seconds",[1593],"dehydratedState.queries.2.state.data.6.sortTime",[1607],"dehydratedState.queries.2.state.data.6.activitySummary.latestCommentTime.seconds",[1593],"dehydratedState.queries.2.state.data.6.activitySummary.latestChangeTime.seconds",[1593],"dehydratedState.queries.2.state.data.6.generationInfo.generation",[1593],"dehydratedState.queries.2.state.data.6.redirectInfo",[1600],"dehydratedState.queries.2.state.data.7.createTime.seconds",[1593],"dehydratedState.queries.2.state.data.7.updateTime.seconds",[1593],"dehydratedState.queries.2.state.data.7.sortTime",[1607],"dehydratedState.queries.2.state.data.7.activitySummary.latestCommentTime",[1600],"dehydratedState.queries.2.state.data.7.activitySummary.latestChangeTime.seconds",[1593],"dehydratedState.queries.2.state.data.7.generationInfo.generation",[1593],"dehydratedState.queries.2.state.data.7.redirectInfo",[1600],"dehydratedState.queries.2.state.data.8.createTime.seconds",[1593],"dehydratedState.queries.2.state.data.8.updateTime.seconds",[1593],"dehydratedState.queries.2.state.data.8.sortTime",[1607],"dehydratedState.queries.2.state.data.8.activitySummary.latestCommentTime.seconds",[1593],"dehydratedState.queries.2.state.data.8.activitySummary.latestChangeTime.seconds",[1593],"dehydratedState.queries.2.state.data.8.generationInfo.generation",[1593],"dehydratedState.queries.2.state.data.8.redirectInfo",[1600],"dehydratedState.queries.2.state.data.9.createTime.seconds",[1593],"dehydratedState.queries.2.state.data.9.updateTime.seconds",[1593],"dehydratedState.queries.2.state.data.9.sortTime",[1607],"dehydratedState.queries.2.state.data.9.activitySummary.latestCommentTime",[1600],"dehydratedState.queries.2.state.data.9.activitySummary.latestChangeTime.seconds",[1593],"dehydratedState.queries.2.state.data.9.generationInfo.generation",[1593],"dehydratedState.queries.2.state.data.9.redirectInfo",[1600],"dehydratedState.queries.2.state.data.10.createTime.seconds",[1593],"dehydratedState.queries.2.state.data.10.updateTime.seconds",[1593],"dehydratedState.queries.2.state.data.10.sortTime",[1607],"dehydratedState.queries.2.state.data.10.activitySummary.latestCommentTime",[1600],"dehydratedState.queries.2.state.data.10.activitySummary.latestChangeTime.seconds",[1593],"dehydratedState.queries.2.state.data.10.generationInfo.generation",[1593],"dehydratedState.queries.2.state.data.10.redirectInfo",[1600],"dehydratedState.queries.2.state.data.11.createTime.seconds",[1593],"dehydratedState.queries.2.state.data.11.updateTime.seconds",[1593],"dehydratedState.queries.2.state.data.11.sortTime",[1607],"dehydratedState.queries.2.state.data.11.activitySummary.latestCommentTime.seconds",[1593],"dehydratedState.queries.2.state.data.11.activitySummary.latestChangeTime.seconds",[1593],"dehydratedState.queries.2.state.data.11.generationInfo.generation",[1593],"dehydratedState.queries.2.state.data.11.redirectInfo",[1600],"dehydratedState.queries.2.state.data.12.createTime.seconds",[1593],"dehydratedState.queries.2.state.data.12.updateTime.seconds",[1593],"dehydratedState.queries.2.state.data.12.sortTime",[1607],"dehydratedState.queries.2.state.data.12.activitySummary.latestCommentTime",[1600],"dehydratedState.queries.2.state.data.12.activitySummary.latestChangeTime.seconds",[1593],"dehydratedState.queries.2.state.data.12.generationInfo.generation",[1593],"dehydratedState.queries.2.state.data.12.redirectInfo",[1600],"dehydratedState.queries.2.state.data.13.createTime.seconds",[1593],"dehydratedState.queries.2.state.data.13.updateTime.seconds",[1593],"dehydratedState.queries.2.state.data.13.sortTime",[1607],"dehydratedState.queries.2.state.data.13.activitySummary.latestCommentTime.seconds",[1593],"dehydratedState.queries.2.state.data.13.activitySummary.latestChangeTime.seconds",[1593],"dehydratedState.queries.2.state.data.13.generationInfo.generation",[1593],"dehydratedState.queries.2.state.data.13.redirectInfo",[1600],"dehydratedState.queries.2.state.data.14.createTime.seconds",[1593],"dehydratedState.queries.2.state.data.14.updateTime.seconds",[1593],"dehydratedState.queries.2.state.data.14.sortTime",[1607],"dehydratedState.queries.2.state.data.14.activitySummary.latestCommentTime.seconds",[1593],"dehydratedState.queries.2.state.data.14.activitySummary.latestChangeTime.seconds",[1593],"dehydratedState.queries.2.state.data.14.generationInfo.generation",[1593],"dehydratedState.queries.2.state.data.14.redirectInfo",[1600],"dehydratedState.queries.2.state.data.15.createTime.seconds",[1593],"dehydratedState.queries.2.state.data.15.updateTime.seconds",[1593],"dehydratedState.queries.2.state.data.15.sortTime",[1607],"dehydratedState.queries.2.state.data.15.activitySummary.latestCommentTime.seconds",[1593],"dehydratedState.queries.2.state.data.15.activitySummary.latestChangeTime.seconds",[1593],"dehydratedState.queries.2.state.data.15.generationInfo.generation",[1593],"dehydratedState.queries.2.state.data.15.redirectInfo",[1600],"dehydratedState.queries.5.state.data.document.generationInfo.generation",[1593],"dehydratedState.queries.5.queryKey.2",[1600],"dehydratedState.queries.6.state.data.document.generationInfo.generation",[1593],"dehydratedState.queries.7.state.data.metadata.summary",[1600],"referentialEqualities",{"_1591":1836,"_1596":1837,"_1603":1838,"_1612":1839,"_1618":1840,"_1632":1841,"_1646":1842,"_1660":1843,"_1674":1844,"_1688":1845,"_1702":1846,"_1716":1847,"_1730":1848,"_1744":1849,"_1758":1850,"_1772":1851,"_1786":1852,"_1800":1853,"_1814":1854},[1594],[1654,1682,1752],[1610],[1826],[1624],[1638],[1652],[1666],[1680],[1694],[1708],[1722],[1736],[1750],[1764],[1778],[1792],[1806],[1820],"actionData","errors"]