Architecture

Design in Onshape typically beings with a document, which is the container that includes all content related to a specific design. All data in an Onshape document is stored in Elements. Part Studios and Assemblies are two of the most common element types in a design. Throughout the design process, creating versions can be useful for product development management while working on the “Main” workspace. See also:

• The API Introduction page for information on how documents, workspaces, and elements are assembled into a URL.
• The Associativity page for information on how Parts, Assemblies, and Elements relate to each other.

Elements

All data in an Onshape document are stored in Elements (represented as tabs in the user interface). Onshape documents contain five kinds of elements:

• Part Studio: Contains zero or more parts
• Assembly: Contains zero or more parts or assemblies
• Blob (Binary Large OBject): Can be provided by a partner or by the end user. For example, the user can upload a PDF file, an image, or a text file. Partner applications can store arbitrary data, but we recommend using the structured storage available in an element for better integration.
• Application: Presents an iframe to the user. The user interface is managed by a server that can be provided by a third-party. Onshape Drawings are a special case of an application element.
• Feature Studio: Contains the definition for Onshape Features, which are defined in FeatureScript.

Workspaces, Versions, and Microversions

A document is stored in Onshape as a collection of changes.

• You can think of a workspace as a branch of the document, similar to a branch in a source control system. Documents can be branched to create new workspaces.
• Each individual change to the document creates a new document microversion. As the document is edited, changes are applied to the active workspace, creating new microversions.
• Periodically, the user may designate versions of the document. A version is a named snapshot of the entire document at some point in time (that is, at some microversion).

You cannot change a version or microversion of a document; all changes are applied to a workspace (and create a new microversion). Thus, while in general the GET methods of the API can read from a version, microversion, or workspace, the POST methods generally require a workspace, and create a new microversion when data is written to the document. (An exception is that it is possible to set metadata within a version; this does not create a new microversion).

The following IDs are used by many of the APIs. Each ID (except for Geometry IDs such as Part, Face and Edge) is a 24-character string that is used internally by Onshape to uniquely identify the resource. The Geometry IDs are variable-length strings used to resolve to a specific geometric entity within a model.

Note that a Part ID may reference a part that no longer exists if the model is changed, so it is best to specify a Version or Microversion to pick the context for the Part ID. Note that even with the Version or Microversion, internal changes to the Onshape system may also change the Part ID. Onshape provides mechanisms for maintaining persistent references. See the Associativity page for more information. Face and Edge IDs are used in similar ways.

The following table identifies Onshape concepts and the corresponding Git concepts. Note that this is not a direct mapping, and the implementation of the concepts is very different.

Linked Documents

Although a document can contain a complex model tree involving many Part Studio and Assembly elements, it is often more efficient to split the content into multiple documents. Connections between documents always refer to a specific version of the target document. Once a version is used as the target of a linked document, that document version is preserved as long as any document references it, even if the containing document is deleted. Additionally, any user that has access to the referring document will have limited read access to the target document, regardless of what permissions are currently on the target document.

Configurations

Onshape Part Studios can be constructed to be configurable using Onshape Configurations. API calls that reference Part Studios (primarily within the Parts and Part Studios APIs) often accept a configuration parameter that identifies what specific configuration of the Part Studios is being referenced. When not specified, the API implementation typically uses the configuration that is currently selected within the Part Studio. An interactive ad-hoc API call might not behave consistently in an application, so be sure to specify the configuration parameter where applicable.

Onshape Data Model

Onshape data is stored in replicated databases in the cloud. The Onshape data model is influenced by the Git data model and similar source code repositories.

Documents contain elements. Elements are presented as tabs in the user interface. With some exceptions, all data in a document is stored within an element. The following table describes what data stored in each Element type:

Note that Onshape Drawing elements are Application elements managed by Onshape.

Tessellated data is not stored persistently in Onshape; it is generated on demand for display by the Onshape clients, or in response to application REST API requests. This data may be cached for performance.

Document data

All elements, including Assemblies, Part Studios, Drawings, or even apps, are history based. Each change to an element or set of elements represents a unique record in the document’s history, known as a microversion. The document can be restored to that particular state any time in the future.

Part Studio data

The Part Studio element is defined by a list of features, some of which (e.g., a sketch), may have a complex internal structure composed of entities. Part Studio features and entities are referenced by unique persistent identifiers. Part Studio features and entities can appear, disappear, and reappear depending on the current microversion of the model.

Assembly data

The Assembly element is defined as a list of assembly features and a tree of subassemblies/part instances. Occurrence ID is a unique persistent identifier of an occurrence of a part in the assembly structure.

External application data

An external application has complete control over how it manages/stores documents, however, to take advantage of the Onshape data model, there is a set of endpoints they should use to store state. These are collectively known as the AppElement API.

Model presentation data

A valid model definition usually corresponds to a real-world manufacturable topology, represented internally as a set of parts, faces, edges, and vertices and the set of relations between them. Each of these has a unique identifier in every state of the model. The identifier represents an encoded index in the model’s history, and its value depends on the structure of the model’s history. The value is not guaranteed to be preserved across model changes, and will almost always change if the model changes in significant ways. The model can be tessellated into a set of geometric primitives, which approximate the shape of the model. Tessellated data can be used for visual representation of the model or other processing related to the shape of the model.

The following changes in the topological representation can occur between two microversions of the model:

• New topological entities appear
• Id of existing topology change
• Topological entities disappear
• Existing topological entities are merged into a single entity
• Existing topological entity are split into multiple entities

The model microversion and topology ID can be used to identify topological entities across the model changes. Topology ID defined in a specific microversion can be translated into a set of topology IDs in the current microversion of the model. (The Topology ID is sometimes referred to as a Deterministic ID within Onshape, and is exposed in specific API calls as partId, faceId, etc.). See the PartStudio APIs to see what topology IDs are exposed.