From 55b5950e5ef99243336130ecf806797129528ff3 Mon Sep 17 00:00:00 2001 From: Advait Athreya <89476471+advaitathreya@users.noreply.github.com> Date: Tue, 14 Nov 2023 14:05:04 -0500 Subject: [PATCH] dev: edit typos and formatting in documentation --- docs/alpha.md | 4 ++-- docs/collections.md | 6 +++--- docs/data.md | 7 ++++--- docs/discussions.md | 6 +++--- docs/federation.md | 2 +- docs/history.md | 4 ++-- docs/incentives.md | 2 +- docs/index.md | 2 +- docs/namespaces.md | 6 +++--- docs/protocol.md | 4 ++-- docs/schemas.md | 10 +++++----- docs/using.md | 10 +++++----- docs/versioning.md | 8 ++++---- 13 files changed, 36 insertions(+), 35 deletions(-) diff --git a/docs/alpha.md b/docs/alpha.md index b6c6e2f..0772c34 100644 --- a/docs/alpha.md +++ b/docs/alpha.md @@ -4,13 +4,13 @@ We are rolling out an initial version of Underlay dubbed `build-target-1`. This 1. The definition and use of shared schemas 2. The workflow and interfaces for adding data -3. The interfaces for using data stored in different collections How do you want to use data? +3. The interfaces for using data stored in different collections (How do you want to use data?) ## 1. Shared schemas Some questions we're interested in understanding: - Are there common schemas you already use in practice? -- Are there specific things that you wish were consistentl represented in a common way across groups? +- Are there specific things that you wish were consistently represented in a common way across groups? ## 2. Data workflows - What tools do you use for data work at the moment? diff --git a/docs/collections.md b/docs/collections.md index 622329f..d6b072f 100644 --- a/docs/collections.md +++ b/docs/collections.md @@ -4,14 +4,14 @@ Collections are the primary element in Underlay and its associated protocols. Mo A collection should be portable - it should contain everything about itself (e.g. [Discussions](/discussions) should be stored as data within the collection, not in another format outside of the collection itself). -Collections have a human-readbale name and a canonical `shortId`. These are concatenated to produce the URL of the collection: `underlay.org/jordan/${human-readable-name}-${shortId}`. +Collections have a human-readable name and a canonical `shortId`. These are concatenated to produce the URL of the collection: `underlay.org/jordan/${human-readable-name}-${shortId}`. The canonical `shortId` provides a persistent means for routing to a collection across changes in namespace, transfers of collections to other owners, collection renames, and namespace or collection-name typos. ## Collections as building blocks In the early days of the Underlay, we envisioned a singular, monolithic knowledge graph akin to Freebase or Google's knowledge graph. As the project matured, we realized that a misalignment of that approach with our mission is that a singular graph can only possibly represent a single curatorial perspective. We don't believe such a singular perspective can exist ethically or logistically (who is going to curate such a thing?!). -Our current vision for the Underlay is one where many such graphs are created by using collections as building blocks. Each collection represents a focused, curated set of data. Piecing many of them together, like using Legos to construct a larger structure, it is possible to build a large, expert-curated, deeply provenanced knowledge graph. We envision there will many large collections that are simply curated perspectives on which sub-collections are trustworthy, verifiable, and appropriate. Similarly to how a single open-source codebase can have a deeply nested tree of dependencies, we envision collections that have a deeply nested tree of dependency-collections. +Our current vision for the Underlay is one where many such graphs are created by using collections as building blocks. Each collection represents a focused, curated set of data. Piecing many of them together, like using Legos to construct a larger structure, it is possible to build a large, expert-curated, deeply provenanced knowledge graph. We envision there will many large collections that are simply curated perspectives on which sub-collections are trustworthy, verifiable, and appropriate. Similar to how a single open-source codebase can have a deeply nested tree of dependencies, we envision collections that have a deeply nested tree of dependency-collections. -Similarly to how an opensource code package defines an API that is used to integrate it into a larger codebase, Underlay collections define a schema that allows the data to be mapped into a larger database appropriately. +Similar to how an open-source code package defines an API that is used to integrate it into a larger codebase, Underlay collections define a schema that allows the data to be mapped into a larger database appropriately. diff --git a/docs/data.md b/docs/data.md index 8a8fdc9..1d5bd0e 100644 --- a/docs/data.md +++ b/docs/data.md @@ -1,14 +1,15 @@ # Data -Data in Underlay can be stored in any manner technically appropriate for a given architecture. The key conssistency is making data available to other collections and to [exports](using.md) with a consistent interface. Whether data is stored in flat files, a database, or some future architecture should be irrelevant. In this way, we say that Underlay data is 'storage agnostic'. Underlay does not prescribe how data is stored, rather, the interfaces that must be implemented in making that data avialable. +Data in Underlay can be stored in any manner technically appropriate for a given architecture. The key consistency is making data available to other collections and to [exports](using.md) with a consistent interface. Whether data is stored in flat files, a database, or some future architecture should be irrelevant. In this way, we say that Underlay data is 'storage agnostic'. Underlay does not prescribe how data is stored, rather, the interfaces that must be implemented in making that data available. ## Current implementation At present, data is added to collections by uploaded CSV files. This basic approach is the most common one we've heard requested. A user with sufficient permissions to a collection can upload a CSV file which, along with its Mapping produce an [assertion](protocol.md). + Our intent is to implement many modes of adding data that all generate a compliant assertion. Some example input approaches: -- **Web UX:** Building a table-like data editor directly into underlay.org. Values in the table can we edited, new rows can be inserted, or deletions can be made. Such an interface could be made available to different permission levels, some requiring approval by an administrator before being included as a viable assertion. -- **API:** Building an API to allow programmatic insertion, editing, and deletion of collection data. This would allow scripting to be written that automate the process of shaping and uploading new data into a collection. +- **Web UX:** Building a table-like data editor directly into underlay.org. Values in the table can be edited, new rows can be inserted, or deletions can be made. Such an interface could be made available to different permission levels, some requiring approval by an administrator before being included as a viable assertion. +- **API:** Building an API to allow programmatic insertion, editing, and deletion of collection data. This would allow scripts to be written that automate the process of shaping and uploading new data into a collection. - **Web Forms:** Using the API to provide hosted web forms that can be used to generate schema-compliant data additions. Analogous to a web form populating a new row in a spreadsheet, we can have web forms populate a new set of entities in a collection. ## Collaborative data diff --git a/docs/discussions.md b/docs/discussions.md index b2302e1..6e99f63 100644 --- a/docs/discussions.md +++ b/docs/discussions.md @@ -6,7 +6,7 @@ Discussions are implemented by automatically adding a `Discussion` type to the c ## Discussion UI -- Discussions can be created from the discussion tab - - [Show image] +- Discussions can be created from the discussion tab. + - Discussions can be created from the data viewer to scope it to a specific data point. - - [Show image] \ No newline at end of file + \ No newline at end of file diff --git a/docs/federation.md b/docs/federation.md index f74d3b5..bdec166 100644 --- a/docs/federation.md +++ b/docs/federation.md @@ -1,5 +1,5 @@ # Federation -Over the course of the project, we've explored maybe different architectures for Underlay. At the core of this consideration is a tension between the simplicity and accessibility of a system, and the eventual power dynamics and restrictions that such a system imposes. Centralized systems are cheaper, more efficient, and quickly to develop, but they risk placing too much power in the hands of the central hosting entity. +Over the course of the project, we've explored many different architectures for Underlay. At the core of this consideration is a tension between the simplicity and accessibility of a system, and the eventual power dynamics and restrictions that such a system imposes. Centralized systems are cheaper, more efficient, and quick to develop, but they risk placing too much power in the hands of the central hosting entity. Purely distributed systems offer technical assurances against such risks, but in practice are difficult to use, grow, and develop. In the most extreme case, they play into a fallacy of trustless systems based on technical proofs. We do not advocate for trustless systems, as we simply don't believe such things are possible once you enter the realm of social structures and culture. diff --git a/docs/history.md b/docs/history.md index f09124b..3d71230 100644 --- a/docs/history.md +++ b/docs/history.md @@ -10,7 +10,7 @@ There were several catalysts that led discussions about a new project called the - Danny's experience with founding [Metaweb](https://en.wikipedia.org/wiki/Metaweb) and their development (and eventual sale) of [Freebase](https://en.wikipedia.org/wiki/Freebase_(database)). Freebase was [shut down by Google in 2016](https://groups.google.com/g/freebase-discuss/c/WEnyO8f7xOQ), and Danny knew an open version of a global knowledge graph still possible and critical. - Travis and Thariq Shihipar had been developing early versions of [PubPub](https://www.pubpub.org) in 2015 and 2016. Initially, PubPub was both a frontend for fast iteration of scholarly articles, and a backend for long-term archival of such documents. Merging these two things created a very uncomfortable interface — one that was simultaneously trying to reduce friction to make quick, iterative changes while also notifying people that all changes would be permanently catalogued in a distributed database forever. Yikes. The archival layer of PubPub was broken off as it became clear there was value in having a separate system for long-term collaborative storage of persistent data. - SJ's experience and involvement with WikiData led to enthusiasm about the opportunities in this space and insight into what was still lacking. -- As part of his PhD general exames, Travis built [DbDb](https://notes.knowledgefutures.org/pub/hevceylu). The idea behind DbDb was to allow users to publish not just datasets, but the lineage of how a dataset was processed and transformed over time, allowing alternative analyses to be 'forked' from any point in a datasets processing timeline. +- As part of his PhD general exams, Travis built [DbDb](https://notes.knowledgefutures.org/pub/hevceylu). The idea behind DbDb was to allow users to publish not just datasets, but the lineage of how a dataset was processed and transformed over time, allowing alternative analyses to be 'forked' from any point in a dataset's processing timeline. ## Support from Protocol Labs Beginning in 2018, Joel Gustafson began working at [Protocol Labs](https://protocol.ai/), who generously allowed him to work full-time on research and development of the Underlay project. Until 2021, Joel was the only person working full-time on the technical components of the project. @@ -64,4 +64,4 @@ With time, we realized that the idea of a singular knowledge graph was rather fr Instead of a single, global, distributed knowledge graph, the notion of Collections emerged. A collection can be thought of as a contained, singularly curated, knowledge graph. This could be as broad as 'all human knowledge' or as narrow as 'taco shops in my neighborhood'. The critical feature of collections though is that they can be designed to be composable. That is, larger and broader knowledge graphs could be built by pulling together smaller knowledge graphs curated by experts on the given topic. And as an extension, many such large and broad knowledge graphs could exist simultaneously based on which collections they decide are relevant for their collection. -Collections thus can be viewed as a knowledge graph of specific size, authority, trustworthyness, and purpose that represent a singular curational perspective. So rather than a singular, global knowledge graph - we have a network of knowledge graphs that can be assembled, composed, and re-mixed to match a given purpose and perspective. +Collections thus can be viewed as a knowledge graph of specific size, authority, trustworthiness, and purpose that represent a singular curational perspective. So rather than a singular, global knowledge graph - we have a network of knowledge graphs that can be assembled, composed, and re-mixed to match a given purpose and perspective. diff --git a/docs/incentives.md b/docs/incentives.md index 3233f99..4aa8628 100644 --- a/docs/incentives.md +++ b/docs/incentives.md @@ -1,6 +1,6 @@ # Incentives -A key to Underlay's success is being able to provide incentives for creating, curatoring, and using collections. Currently, the incentives to create and maintain a public dataset are underwhelming when compared to the cost of actually doing so. There are a few key features we think can improve the situation: +A key to Underlay's success is being able to provide incentives for creating, curating, and using collections. Currently, the incentives to create and maintain a public dataset are underwhelming when compared to the cost of actually doing so. There are a few key features we think can improve the situation. ## Incentivizing useful datasets. A common practice when publishing a public dataset is to simply upload a flat file to a data server. This server can then give you a download count to suggest how useful people find the dataset to be. We think we can do better with a few key features: diff --git a/docs/index.md b/docs/index.md index 2310bf2..3f96d52 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,4 +14,4 @@ Our first step in building towards that vision is a central underlay.org platfor While there are significant technical elements to the project, we are heavily focused on the social and cultural requirements that must be addressed in order for public, collaborative data to flourish. As such, we strive to prioritize simple and accessible design patterns that can be understood and used by many, rather than complex technical patterns that may provide higher customization or efficiency but require deep expertise. ## Why is this work important? -Knowledge is often exchanged in formats optimized for computers, and then used to render webpages, maps, diagrams, tables and text for human consumption. It is also used directly by machines to navigate vehicles, trade stocks, control appliances, design structures, formulate scientific hypotheses, order search results, and much more. But today, most of these machine-readable data sources are privately held and controlled, and the ones that do exist publicly are fragmented and don’t work well with each other. Indeed, at the moment it seems the only way to leverage the power of a large dataset is to control it privately and implement business operations around staffing its maintenance and usage for the purpose of private benefit. The goal of the Underlay is to improve the way that public data is created, curated, and used such that it can be shared and used for public benefit. +Knowledge is often exchanged in formats optimized for computers, and then used to render webpages, maps, diagrams, tables, and text for human consumption. It is also used directly by machines to navigate vehicles, trade stocks, control appliances, design structures, formulate scientific hypotheses, order search results, and much more. But today, most of these machine-readable data sources are privately held and controlled, and the ones that do exist publicly are fragmented and don’t work well with each other. Indeed, at the moment it seems the only way to leverage the power of a large dataset is to control it privately and implement business operations around staffing its maintenance and usage for the purpose of private benefit. The goal of the Underlay is to improve the way that public data is created, curated, and used such that it can be shared and used for public benefit. diff --git a/docs/namespaces.md b/docs/namespaces.md index 34962b9..a0c8151 100644 --- a/docs/namespaces.md +++ b/docs/namespaces.md @@ -1,10 +1,10 @@ # Namespaces -Namespaces in Underlay are human-readable strings that give context to the authority behind a given collection. A single namespace is given to each User and Community. The pool of available namespaces is shared amonst all users and communities. +Namespaces in Underlay are human-readable strings that give context to the authority behind a given collection. A single namespace is given to each User and Community. The pool of available namespaces is shared amongst all users and communities. Navigating to a namespace URL (e.g. `underlay.org/jordan` or `underlay.org/nasa`) will lead to a user's or organization's profile. The profile will list all collections associated with that namespace and other profile details. Collections live at a URL path after a namepsace, e.g. `underlay.org/${namespace}/${collection-slug}${collection-shortId}`. -Namespaces are not persistent! Users or communities may change the namespace over time (though, many won't), so they can not do not guarantee a persistent, permanent address. +Namespaces are not persistent! Users or communities may change the namespace over time (though, many won't), so they cannot and do not guarantee a persistent, permanent address. It will be common practice to refer to a schema or collection using namespaces and collection slugs, but permanent URIs will use collection shortIds or full ids of the collection or namespace. For example @@ -25,7 +25,7 @@ collectionShortId: hsbga72 This allows us to resolve collections, specific schema or collection versions despite a namespace or collection-string changing, as long as the collection `shortId` is maintained. -Schemas will typically be addressed be referenced by their most recent human-readable URI. For example: +Schemas will typically be addressed or be referenced by their most recent human-readable URI. For example: ``` schema: jordan/map-data-hsbga@2.1 diff --git a/docs/protocol.md b/docs/protocol.md index b0f6688..5740f7f 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -8,7 +8,7 @@ Our current answer is that the purpose of the Underlay is to make public data mo With that in mind, it is often easier to identify what parts of that problem Underlay does _not_ address. For example, we are not trying to increase query-speed of data (i.e. we're not a database), and we're not trying to improve transfer sizes (i.e. we're not a compression algorithm). -In fact, nearly all of the technical components that one typically thinks of when considering public datasets have already been considered and addressed by past efforts around the Semantic Web, RDF, and modern efforts on IPFS, IPLD, Dat, and other open data projects. However, despite the technical expertise brought to these projects, the reality of public data still leaves us wanting. As such, we identify that a missing piece we can address is the social dynamics of using public data. Our approach is to identify simple, well-established technical components that can serve as the basis for facilitating more effective, equitable, and sustainble processes. +In fact, nearly all of the technical components that one typically thinks of when considering public datasets have already been considered and addressed by past efforts around the Semantic Web, RDF, and modern efforts on IPFS, IPLD, Dat, and other open data projects. However, despite the technical expertise brought to these projects, the reality of public data still leaves us wanting. As such, we identify that a missing piece we can address is the social dynamics of using public data. Our approach is to identify simple, well-established technical components that can serve as the basis for facilitating more effective, equitable, and sustainable processes. The Underlay is premised on the idea that a knowledge graph can be constructed from a series of distributed transactions called assertions. Multiple assertions are combined through a process called reduction and can be curated into useful groupings using collections. @@ -25,7 +25,7 @@ A toy example of an assertion is simply something like } ``` -In english: 'Jude says that Rosalind Franklin was born in 1920'. +In English: 'Jude says that Rosalind Franklin was born in 1920'. ## Reduction diff --git a/docs/schemas.md b/docs/schemas.md index 13a0ff0..d191c46 100644 --- a/docs/schemas.md +++ b/docs/schemas.md @@ -3,25 +3,25 @@ An important first step in any data project is building the model of how you wish to represent your data. Especially in collaborative data projects, simply communicating the shape of the data involved is a major part of the challenge. In building schemas, there are two common misteps we see repeated in different groups: ## Mistep 1: Optimizing for consensus -In developing Underlay, we've spoken with many groups who have lamented the challenge of settling on a schema definition with a committee of stakeholders. We've heard anecdotes of folks spending more time in email, zoom calls, and forums debating what the ideal schema is than they did collecting the data. This creates an enormous barrier to starting work, it biases towards premature optimization, and it stymies excitement for projects. +In developing Underlay, we've spoken with many groups who have lamented the challenge of settling on a schema definition with a committee of stakeholders. We've heard anecdotes of folks spending more time in emails, zoom calls, and forums debating what the ideal schema is than they did collecting the data. This creates an enormous barrier to starting work, it biases towards premature optimization, and it stymies excitement for projects. As such, we've prioritized a design that trades in a-priori schema consensus for simple, post-hoc usage-driven schema adjustments. Rather than forcing everyone to agree at the beginning, simply start doing what seems right, and iterate over time to find what actually promotes collaboration in practice. The best schema is the one you'll actually use. Allowing them to be fluid allows collaboration to emerge over time. ## Mistep 2: Optimizing for storage -The first time many projects need to consider their schema is when they try to insert their data into a database. The database will require a schema, and often offer techniques for optimizing queries, storage size, and other datbase-centric parameters. While this is a critical technical step, it can create a schema that is does not align with the mental model people (especially non-technical people) typically have for such data. It requires the person to thing like a computer, as opposed to letting them think like a human and have the computer adapt. +The first time many projects need to consider their schema is when they try to insert their data into a database. The database will require a schema, and often offer techniques for optimizing queries, storage size, and other database-centric parameters. While this is a critical technical step, it can create a schema that does not align with the mental model people (especially non-technical people) typically have for such data. It requires the person to thing like a computer, as opposed to letting them think like a human and have the computer adapt. As such, we've prioritized schema declarations that are storage-agnostic. Underlay schemas are intended to mirror the mental model people often have for a given dataset. The technical bits that allow for optimized querying and storage come at another stage in the process. ## Starting with Types In building an Underlay schema, we advocate to begin by describing the different entities that are represented in your dataset. Are there people, cars, food, animals? -[TODO: technical dive on naming all the parts of a schema] + ## Adopting common Types Unsurprisingly, many people are interested in data about a common set of things. Many folks want to represent a person, a location, an event, etc. There exist many best practices about how to represent such things, and we believe that removing the burden of inventing a type for common things from scratch is a great way to reduce the overhead and cost of beginning a data project. -Underlay allows you to reference a type from another schema directly. This allows you to simply compose schemas from the best practices, tailored to your use case. We expect there to be certain communities and individuals who maintain collections with the sole purpose or providing common, standardized typed for common things. +Underlay allows you to reference a Type from another schema directly. This allows you to simply compose schemas from the best practices, tailored to your use case. We expect there to be certain communities and individuals who maintain collections with the sole purpose of providing common, standardized Types for common things. -Beyond reduceing the cost of designing your schema, this also makes it trivial to interoperate with other collections that also use that type. It provides a path for the ecosystem to coalesce around agreements that both reduce the overhead and make interopability simple. +Beyond reducing the cost of designing your schema, this also makes it trivial to interoperate with other collections that also use that Type. It provides a path for the ecosystem to coalesce around agreements that both reduce the overhead and make interoperability simple. ## Migrating across schema changes In cases where a schema migration is possible, the most recent version of data is taken, mapped to a new schema, and issued as a new version. Future patch versions are reduced against that newly-migrated base version of the data, so there is never a case where you are reducing two assertions that have a different underlying schema. \ No newline at end of file diff --git a/docs/using.md b/docs/using.md index d3f6e77..659d770 100644 --- a/docs/using.md +++ b/docs/using.md @@ -1,7 +1,7 @@ # Using Collections Our intent is to make it quick and simple to use existing Underlay collections. There will likely be several iterations on designing the best approach for achieving this. -There are a number of important elements that a user of data may want to customize for thier use case: +There are a number of important elements that a user of data may want to customize for their use case: - Shape of the output data (e.g. how the data is nested and which fields are included) - Key names of output data (e.g. to align with production systems) @@ -18,14 +18,14 @@ At present, exports are generated as static, cached files. The files can either Export files can specify a mapping that allows users to choose which fields they want included in their exported file, as well as rename those fields to align with their use case. -At present, there is no way to filter data from an export beyond including or excluded a specific class or attribute. +At present, there is no way to filter data from an export beyond including or excluding a specific class or attribute. ## Future Approach: Queries -An improved interface for exports would be to allow users to generate a query whose result is cached and storage. The output result may be similar to static cached files (e.g. a JSON file or CSV file), but they would have more granular control over which data is included in these output files. +An improved interface for exports would be to allow users to generate a query whose result is cached and stored. The output result may be similar to static cached files (e.g. a JSON file or CSV file), but they would have more granular control over which data is included in these output files. ## Future Approach: Hosted instances -One future interface we intend to implement is the ability to quickly stand up a private, hosted database that is populated with the collection's data or a queried subset of the data. This hosted instance would be production-grade and could be immediately used in a production environment. Settings on whether the content of the hosted instance is automaticall incremented as new collection versions are published would be configurable. +One future interface we intend to implement is the ability to quickly stand up a private, hosted database that is populated with the collection's data or a queried subset of the data. This hosted instance would be production-grade and could be immediately used in a production environment. Settings on whether the content of the hosted instance is automatically incremented as new collection versions are published would be configurable. -This would give users a simple way to take existing collections and using them in production environments quickly, and with low maintenance overhead. \ No newline at end of file +This would give users a simple way to take existing collections and use them in production environments quickly, and with low maintenance overhead. \ No newline at end of file diff --git a/docs/versioning.md b/docs/versioning.md index d864c5b..3e0cc58 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -5,13 +5,13 @@ Collections are versioned with a strict numbering system. The system takes inspi The primary difference is that collection versions are defined such that they have specific computational meaning: - **Patches: 0.0.x** Patch versions mean that the data has changed, but the schema is the same. Systems using a previous patch version can be updated to use the new version with no structural change. -- **Minor: 0.x.0** Minor versions mean that there schema was changed, but it was changed in a way that can be computationally migrated. For example, a property name was updated from `naem` to `name`. This is a trivial migration, and systems using previous minor versions may require minor changes to accomodate the new version. -- **Major: x.0.0** Major versions mean that the shcema was changed in a way that is not computationally trivial. Typically, systems using previous major versions will need to be structurally updated to accomodate the new version. In rare occassions, a major version can also be forced despite no changes to the schema or data to indicate a ne semantic meaning to the data. For example, some groups may want to issue a major change from `0.7.29` to `1.0.0` to indicate a dataset is out of a 'beta-testing' phase and is ready for production use. +- **Minor: 0.x.0** Minor versions mean that their schema was changed, but it was changed in a way that can be computationally migrated. For example, a property name was updated from `naem` to `name`. This is a trivial migration, and systems using previous minor versions may require minor changes to accomodate the new version. +- **Major: x.0.0** Major versions mean that the schema was changed in a way that is not computationally trivial. Typically, systems using previous major versions will need to be structurally updated to accomodate the new version. In rare occassions, a major version can also be forced despite no changes to the schema or data to indicate a new semantic meaning to the data. For example, some groups may want to issue a major change from `0.7.29` to `1.0.0` to indicate a dataset is out of a 'beta-testing' phase and is ready for production use. -These strict version definitions mean that the appropriate update to a version number can typically be inferred computationally (i.e. users typically won't need to manually specify the type of version increment). If we see that the data changed, but the schema remains the same, we know it is a patch version. This provides consumers of the data with a strong guarantee about the interopability of new versions with existing systems. +These strict version definitions mean that the appropriate update to a version number can typically be inferred computationally (i.e. users typically won't need to manually specify the type of version increment). If we see that the data changed, but the schema remains the same, we know it is a patch version. This provides consumers of the data with a strong guarantee about the interoperability of new versions with existing systems. ## Schema version reference Given that patch versions represent a data change without a schema change, we know that `2.1.18` has an identical schema to `2.1.19` and all `2.1.x` versions. As such, schemas can be referenced using just the major and minor version numbers. For example: `jordan/map-data@2.1`. ## Assertions -A new version of a collection may be produced by many [assertions](protocol.md). There is no need to connect each assertion with a new version. In practice, we expect that each new version will be the reslt of multiple assertions, potentially from a varied list of collaborators. It is up to the discretion of the collection owner when to publish a new version. They could publish a new version on every new assertion, or they could publish a new version after 100 assertions that were generated by a public web form after filtering a few of the results out for spam. \ No newline at end of file +A new version of a collection may be produced by many [assertions](protocol.md). There is no need to connect each assertion with a new version. In practice, we expect that each new version will be the result of multiple assertions, potentially from a varied list of collaborators. It is up to the discretion of the collection owner when to publish a new version. They could publish a new version on every new assertion, or they could publish a new version after 100 assertions that were generated by a public web form after filtering a few of the results out for spam. \ No newline at end of file