Ontology

A Swift library for working with structured data. This library provides JSON-LD serializable types that can represent entities from various vocabularies, with a focus on Schema.org. It includes convenience initializers for types from Apple frameworks, like Contacts and EventKit.

Requirements

• Swift 6.0+ / Xcode 16+
• macOS 14.0+ (Sonoma)
• iOS 17.0+

Installation

Swift Package Manager

Add the following to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/loopwork-ai/ontology.git", from: "0.6.0")
]

Supported Types

Schema.org Vocabulary

Supported Schema.org types and their Apple framework equivalents:

Schema.org Type	Apple Framework Type	Description
ContactPoint	CNInstantMessageAddress	Represents a method of contact like instant messaging
DateTime	Date	Represents a date and time with ISO 8601 formatting
Event	EKEvent	Represents an event with start/end dates, location, etc.
GeoCoordinates	CLLocation	Represents geographic coordinates with latitude, longitude, and optional elevation
Organization	CNContact	Represents an organization with properties like name and contact info
Person	CNContact	Represents a person with properties like name, contact info, and relationships
Place	MKPlacemark, MKMapItem	Represents a geographical location, specific address, or point of interest
PlanAction	EKReminder	Represents a planned action or task with properties like name, description, due date, and completion status
PostalAddress	CNPostalAddress	Represents a physical address with street, city, region, etc.
QuantitativeValue	Measurement	Represents measurements with standardized units using UN/CEFACT Common Codes
Trip	MKDirections.Response, MKDirections.ETAResponse	Represents an itinerary of visits to one or more places with optional arrival/departure times

Apple WeatherKit Vocabulary

Additional types supporting Apple WeatherKit:

Type	WeatherKit Type	Description
WeatherForecast	DayWeather, HourWeather, MinuteWeather	Detailed weather forecast including temperature, precipitation, wind, sun/moon data
WeatherConditions	CurrentWeather, HourWeather	Current or hourly weather conditions including temperature, wind, and humidity

Usage

Creating objects and encoding as JSON-LD

import Ontology

// Create a Person
var person = Person()
person.givenName = "John"
person.familyName = "Doe"
person.email = ["[email protected]"]

// Create an organization
var organization = Organization()
organization.name = "Example Corp"

// Associate person with organization
person.worksFor = organization

// Encode to JSON-LD
let encoder = JSONEncoder()
let jsonData = try encoder.encode(person)
print(String(data: jsonData, encoding: .utf8)!)

// Output:
// {
//   "@context": "https://schema.org",
//   "@type": "Person",
//   "givenName": "John",
//   "familyName": "Doe"
// }

Initializing from Apple framework types

import Ontology
import Contacts

// Convert from Apple's CNContact to Schema.org Person
let contact = CNMutableContact()
contact.givenName = "Jane"
contact.familyName = "Smith"
contact.emailAddresses = [
    CNLabeledValue(label: CNLabelHome, 
                   value: "[email protected]" as NSString)
]

// Convert to Schema.org Person
let person = Person(contact)

Configuring DateTime representations

By default, DateTime objects are encoded with their specified time zone, or GMT/UTC if none is specified. You can override the time zone used during encoding by providing a specific TimeZone in the JSONEncoder's userInfo dictionary:

import Ontology

// Create a DateTime object
let dateTime = DateTime(Date())

// Create an encoder that will use the local timezone
let encoder = JSONEncoder()
encoder.userInfo[DateTime.timeZoneOverrideKey] = TimeZone.current

// Or specify a particular timezone
// encoder.userInfo[DateTime.timeZoneOverrideKey] = TimeZone(identifier: "America/New_York")

// Encode using the specified timezone
let jsonData = try encoder.encode(dateTime)

This feature is particularly useful when:

• Working with date-only values that should be interpreted in the user's local timezone
• Ensuring consistent timezone representation across different data sources
• Presenting dates to users in their local timezone regardless of how they were originally stored

So to recap, the date encoding priority is:

1. TimeZone from encoder's userInfo (if provided)
2. TimeZone from the DateTime object (if specified)
3. GMT/UTC (default fallback)

Legal

Apple Weather and Weather are trademarks of Apple Inc. This project is not affiliated with, endorsed, or sponsored by Apple Inc.

License

This project is licensed under the Apache License, Version 2.0.