Skip to main content

GraphQL Schema

:::warning Schema Preview Notice This schema reference represents a preview of select types from OnEarly's API to demonstrate how the platform works. This is not the complete schema and is not representative of the final public API that will be released.

The full production schema will include additional types, enhanced security features, and optimizations before public availability. :::

This schema reference shows key types and concepts from OnEarly's GraphQL API. The examples here illustrate the platform's core functionality and data structures.

API Overview​

OnEarly's GraphQL API provides:

  • Type-safe queries with complete schema introspection
  • Granular permissions enforced at the field level
  • Flexible data fetching to minimize over-fetching
  • Real-time subscriptions for activity feeds and updates
  • Comprehensive error handling with detailed validation messages

Key API Concepts​

Query Structure​

OnEarly's API follows GraphQL best practices with clear, predictable query patterns that mirror the health network structure.

Permission Enforcement​

Every API operation respects OnEarly's permission model - you can only access content that you have explicit permissions for.

Error Handling​

The API provides detailed error messages and validation feedback to help with integration and debugging.

Core Content Types​

ContentValueFields​

Polymorphic value structure that holds different data types. This allows OnEarly to store any type of health information in a consistent format.

type RangeBand {
  min: Float
  max: Float
  label: String
  note: String
}

type RangeValueType {
  ranges: [RangeBand!]!
}

type ContentValueFields {
  stringValue: String         # For text content like notes, names
  numericValue: Float        # For measurements, counts, scores
  booleanValue: Boolean      # For yes/no, true/false flags
  rangeValue: RangeValueType # For reference ranges, acceptable values
  dateValue: String          # For date-only values (YYYY-MM-DD)
  datetimeValue: String      # For full timestamps (ISO 8601)
}

ContentNode​

Individual pieces of health information in the system. Each node represents one discrete piece of health data with its associated metadata.

type ContentNode {
  uuid: UUID!                     # Unique identifier for this content
  value: ContentValueFields!      # The actual data (polymorphic)
  valueType: ValueType!           # How to interpret the value
  unitUuid: UUID                  # Optional unit for numeric values
  unit: Unit                      # Unit details (e.g., "mg/dL")
  affix: Affix                    # Additional display formatting
  contentTypeUuid: UUID!          # Reference to the content type definition
  contentType: ContentType!       # Schema definition for this content
  createdAt: Date!                # When this content was created
  updatedAt: Date!                # When this content was last modified
  occurredAt: Date!               # When the event/measurement occurred
  subjectUuid: UUID!              # Who this content is about
  subjectActor: GenericActor!     # Actor details for the subject
}

ContentType​

Defines the schema and metadata for different kinds of content.

type ContentType {
  uuid: UUID!
  name: String!
  valueType: ValueType!
  immutable: Boolean!
  domain: String!
  domainSource: String!
  description: String
  tags: [String!]!
  units: [Unit!]!
  metadata: JSON
  createdAt: Date!
  updatedAt: Date!
}

ContentNodeEdge​

Defines relationships between content nodes.

type ContentNodeEdge {
  uuid: UUID!
  fromContentUuid: UUID!
  fromContent: ContentNode!
  toContentUuid: UUID!
  toContent: ContentNode!
  edgeType: ContentEdgeType!
  certainty: Certainty
  metadata: JSON
  createdAt: Date!
  updatedAt: Date!
}

ContentActorEdge​

Defines how actors relate to content with specific permissions.

type ContentActorEdge {
  contentUuid: UUID!
  principalType: ContentPrincipalType!
  principalUuid: UUID!
  principalActor: GenericActor!
  scopeGroupUuid: UUID
  scopeGroupActor: GenericActor
  edgeType: ContentActorEdgeType!
  permissions: [ContentPermission!]!
  expiry: Date
  creatorUuid: UUID!
  creatorActor: GenericActor!
  createdAt: Date!
  updatedAt: Date!
}

Actor Types​

Actor Interface​

Base interface for all actors in the system.

interface Actor {
  uuid: UUID!
  id: String
  name: String!
  actorType: ActorType!
  profileImage: ImageVariants
  createdAt: Date!
  updatedAt: Date!
}

GenericActor​

type GenericActor implements Actor {
  uuid: UUID!
  id: String
  name: String!
  actorType: ActorType!
  profileImage: ImageVariants
  createdAt: Date!
  updatedAt: Date!
}

User​

type User implements Actor {
  uuid: UUID!
  id: String
  name: String!
  actorType: ActorType!
  profileImage: ImageVariants
  createdAt: Date!
  updatedAt: Date!
}

Group​

type Group implements Actor {
  uuid: UUID!
  id: String
  name: String!
  actorType: ActorType!
  profileImage: ImageVariants
  visibility: GroupVisibility!
  createdAt: Date!
  updatedAt: Date!
}

Domain and Classification​

Domain​

type Domain {
  uuid: UUID!
  name: String!
  authorUuid: UUID!
  ownedByUuid: UUID!
  createdAt: Date!
  updatedAt: Date!
}

DomainSource​

type DomainSource {
  uuid: UUID!
  name: String!
  url: String
  authorUuid: UUID!
  createdAt: Date!
  updatedAt: Date!
}

Unit​

type Unit {
  uuid: UUID!
  notation: String!           # "mg*dl^-1" - programmatic notation for calculations
  prettyNotation: String!     # "mg×dl⁻¹" - scientific/formatted notation for display
  description: String!        # "milligrams per deciliter"
  authorUuid: UUID!
  ownedByUuid: UUID
  lastUpdatedByAuthorUuid: UUID
  deletedAt: Date
  createdAt: Date!
  updatedAt: Date!
}

RBAC Types​

Permission​

type Permission {
  uuid: UUID!
  slug: String!
  name: String!
  description: String!
  createdAt: Date!
  updatedAt: Date!
}

GroupRole​

type GroupRole {
  uuid: UUID!
  name: String!
  description: String
  isBuiltIn: Boolean!
  groupUuid: UUID!
  group: Group!
  permissions: [Permission!]!
  createdAt: Date!
  updatedAt: Date!
}

UserGroupRole​

type UserGroupRole {
  uuid: UUID!
  userUuid: UUID!
  user: User!
  groupUuid: UUID!
  group: Group!
  roleUuid: UUID!
  role: GroupRole!
  createdAt: Date!
  updatedAt: Date!
}

Enums​

ActorType​

enum ActorType {
  USER     # Individual people with accounts
  SYSTEM   # Automated processes and integrations
  GROUP    # Organizations or teams that users can join
  PUBLIC   # Publicly accessible content
}

GroupVisibility​

enum GroupVisibility {
  PUBLIC   # Discoverable, public info, future auto-join
  PRIVATE  # Discoverable, public info, invite-only
  SECRET   # Not discoverable, hidden info, strictly invite-only
}

ValueType​

enum ValueType {
  STRING     # Text content
  NUMERIC    # Numbers
  BOOLEAN    # True/false values
  DATE       # Date-only values
  DATETIME   # Full timestamp values
  RANGE      # Numeric ranges with min/max
  ENUM       # Predefined options
}

ContentEdgeType​

enum ContentEdgeType {
  CONTAINS     # Parent contains child content
  RELATES_TO   # General relationship between content
}

ContentActorEdgeType​

enum ContentActorEdgeType {
  AUTHORED_BY  # Actor created this content
  SHARED_WITH  # Content has been shared with actor
}

ContentPrincipalType​

enum ContentPrincipalType {
  USER           # Individual user access
  GROUP          # Group entity access (requires special permissions)
  GROUP_MEMBER   # User acting as group member (principal=user, scope=group)
  GROUP_MEMBERS  # All members of a group
  PUBLIC         # Public access
}

ContentPermission​

enum ContentPermission {
  READ     # View content and metadata
  SHARE    # Grant access to other actors
  CREATE   # Add new related content
  UPDATE   # Modify existing content
  DELETE   # Remove content from system
}

Certainty​

enum Certainty {
  ASSERTED    # Explicitly asserted relationship
  INFERRED    # Relationship derived from other data
  SUGGESTED   # Potential relationship based on analysis
}

Scalar Types​

scalar UUID
scalar Date
scalar URL
scalar JSON

Common Types​

PageInfo​

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

ImageVariants​

type ImageVariant {
  contentUuid: UUID!
  url: URL!
}

type ImageVariants {
  original: ImageVariant
  small: ImageVariant
  medium: ImageVariant
  large: ImageVariant
}