README

A canonical base reference for the Claris FileMaker Server OData API, intended as the single source of truth that downstream libraries (MCP servers, JavaScript wrappers, and any future wrappers) conform to and evolve against.

Purpose

This project provides a unified source of conventions and a version-aware capability list for the Claris FileMaker Server OData API. It serves as a common platform to unify FileMaker OData implementations across different languages, runtimes, and tool ecosystems.

The Claris OData API has evolved across server versions (2023, 2024, 2025, 2026) with subtle behavioral differences, undocumented quirks, and version-gated features. Without a shared reference, each wrapper library independently discovers and works around the same issues, leading to divergent implementations and duplicated effort.

This repository solves that by providing:

1. A single, documented contract for what the FileMaker OData API does and does not support — so every wrapper implements the same behavior instead of guessing.
2. A version-aware capability matrix that maps FileMaker Server versions to supported features, query options, and endpoint availability — so wrappers can detect the server version and gate functionality accordingly.
3. A propagation point for API changes — when Claris releases a new FileMaker Server version, the update happens here first, then flows to every derived library.
4. Three explicit categories of coverage:
   • Standard OData features that FileMaker covers.
   • Standard OData features that FileMaker explicitly does not cover (so wrappers don't try to implement them).
   • Non-OData additions specific to FileMaker (containers, scripts, webhooks, custom Prefer headers, metadata annotations, system tables, etc.).

Current downstream implementations

Four projects already consume this spec:

Project	Type	Repository
fms-odata-js	JavaScript/TypeScript client library	https://github.com/fsans/fms-odata-js
fms-odata-py	Python client library	https://github.com/fsans/fms-odata-py
fms-odata-mcp	MCP server for AI agents (TypeScript)	https://github.com/fsans/fms-odata-mcp
fms-odata-webhooks	Webhook handler for FileMaker OData events	https://github.com/fsans/fms-odata-webhooks

What's in this repo

Specification documents (docs/)

The primary deliverable. Read in order — each document builds on the previous:

#	Document	Description
00	Overview	Scope, purpose, version targeting
01	Conformance	OData standard coverage matrix — what FMS supports and what it doesn't
02	Endpoints	Full endpoint reference (URL patterns, methods, status codes)
03	Query Options	$filter, $select, $orderby, $top, $skip, $expand, $count, $apply
04	Authentication	Basic auth, OAuth Bearer token
05	Metadata	$metadata document, annotations, system tables, version detection
06	Scripts	Script execution, scopes, parameters, results
07	Containers	Container field binary/base64 upload and download
08	Batch	$batch requests, changesets, FMS quirks
09	Webhooks	Webhook creation and management
10	Schema Modification	DDL: create/delete tables, fields, indexes
11	Non-OData Additions	FileMaker-specific extensions beyond the OData standard
12	Version Deltas	2023 → 2024 → 2025 → 2026 → future, feature comparison matrix
13	Quirks	Real-world quirks, bugs, and workarounds
14	Reconciliation	Divergence matrix between the two downstream repos

Other contents

schema/
  fms-odata-capabilities.json    # Machine-readable capability manifest (version feature matrix)
packages/
  fms-odata-spec-ts/             # Shared TypeScript types package (@fms-odata/spec-ts on npm)
    src/                        # Endpoint, query, auth, metadata, script, container, batch,
                               # webhook, schema, error, version type definitions
  fms-odata-spec-py/             # Shared Python types package (fms-odata-spec on PyPI)
    src/fms_odata_spec/         # Same surface as the TS package, as stdlib dataclasses
    tests/                      # pytest suite
  fms-odata-spec-php/            # Shared PHP types package (fsans/fms-odata-spec-php on Packagist)
    src/                        # Same surface as the TS package, as readonly DTOs and enums
    tests/                      # PHPUnit suite
_research/                      # Gitignored: cloned source repos used as input

Companion type packages

The spec ships three independent, language-specific type packages that mirror the same API surface. They share no runtime dependency on each other and are versioned/published independently using their respective package managers.

Package	Language	Registry	Install
@fms-odata/spec-ts	TypeScript	npm	npm install @fms-odata/spec-ts
fms-odata-spec	Python	PyPI	pip install fms-odata-spec
fsans/fms-odata-spec-php	PHP	Packagist	composer require fsans/fms-odata-spec-php

TypeScript package (packages/fms-odata-spec-ts/):

cd packages/fms-odata-spec-ts
npm install
npm run build        # tsc -> dist/
npm run typecheck    # tsc --noEmit

Python package (packages/fms-odata-spec-py/):

cd packages/fms-odata-spec-py
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest                           # run the test suite
python -m build                  # build sdist + wheel into dist/

PHP package (run from the repo root, where the Packagist composer.json lives):

composer install
composer test        # PHPUnit (283 tests)
composer analyse     # PHPStan level max
composer check       # tests + static analysis

The Python and PHP folders are intentionally not part of any npm workspace glob; the three package managers are kept fully decoupled. Each package has its own CI workflow scoped to its own path filter (.github/workflows/py-ci.yml for Python, .github/workflows/php-ci.yml for PHP).

Version targeting

The spec covers these FileMaker Server versions, with deltas documented in docs/12-version-deltas.md:

Version	Codename	Status
Claris FileMaker 2023	v20.x	Supported
Claris FileMaker 2024	v21.x	Supported
Claris FileMaker 2025	v22.x	Supported
Claris FileMaker 2026	v26.x	Current (primary reference)
Future / next	—	Reserved section for announced changes

Source of truth

The spec is built from:

1. Official Claris OData API documentation (https://help.claris.com/en/odata-guide/) — primary source.
2. Observed behavior from the two existing wrapper repositories (fms-odata-mcp and fms-odata-js) — real-world quirks, workarounds, and undocumented behaviors.

Where official docs and observed behavior diverge, both are documented and the discrepancy is noted.

How downstream libraries use this

• Read the docs to understand what the API supports and what it doesn't.
• Import the TypeScript types from packages/fms-odata-spec-ts (@fms-odata/spec-ts on npm) for shared type definitions in JS/TS projects.
• Import the Python types from packages/fms-odata-spec-py (fms-odata-spec on PyPI) for shared type definitions in Python projects.
• Import the PHP types from packages/fms-odata-spec-php (fsans/fms-odata-spec-php on Packagist) for shared type definitions in PHP projects.
• Consume the JSON manifest (schema/fms-odata-capabilities.json) to programmatically check feature availability per FileMaker Server version.
• Follow the reconciliation matrix (docs/14-reconciliation.md) when aligning divergent implementations.

OData protocol version

FileMaker Server 2023 (v20.x) implements OData 4.0. FileMaker Server 2024 (v21.x) and later implement partial OData 4.01 at intermediate conformance level, with some exceptions. The URL version segment remains v4 for all versions. See docs/01-conformance.md for the full conformance level and feature support matrix.

Branching model

This repository uses a Git Flow-style workflow:

Branch	Purpose
main	Stable releases only. Every commit on main is a merge from develop and is tagged with a version tag (v1.0.0, v1.1.0, etc.).
develop	Active development. All work lands here first via direct commits or feature branches merged back.

Workflow:

1. Work on develop (or a feature branch off develop).
2. When a set of changes is ready for release, merge develop into main.
3. Tag the merge commit on main with an annotated version tag (vMAJOR.MINOR.PATCH).
4. Push both branches and the tag to origin.

Tagging convention:

• Tags follow semantic versioning: vMAJOR.MINOR.PATCH for the spec/TS package, py-vMAJOR.MINOR.PATCH for the Python package, and MAJOR.MINOR.PATCH (bare, no prefix) for the PHP package.
• Tags are annotated (git tag -a) with a summary of what changed.
• Spec/TS and Python tags are created on main. PHP tags are also created on main (the root composer.json with autoload paths into packages/fms-odata-spec-php/ is what Packagist reads).
• If the @fms-odata/spec-ts npm package version changes, the tag version should match the package version.

PHP package publishing (Packagist):

The PHP package source lives in packages/fms-odata-spec-php/, but a root-level composer.json exists at the repository root with PSR-4 autoload paths pointing into that subdirectory. This is required because Packagist only reads composer.json from the repository root (the default branch). To release:

1. Ensure the work is merged to main and develop.
2. Tag the merge commit on main: git tag -a MAJOR.MINOR.PATCH -m "PHP package MAJOR.MINOR.PATCH — ..."
3. Push: git push origin main --tags
4. On Packagist, the repo URL https://github.com/fsans/fms-odata-spec resolves versions from bare MAJOR.MINOR.PATCH tags on main.

Current tags:

Tag	Package	Description
v1.0.0	spec/TS	Initial spec: 15 docs, JSON manifest, spec-ts types package
v1.1.0	spec/TS	Multi-strategy version detection aligned with fms-odata-mcp
v1.1.1	spec/TS	Script result envelope fix + FMS v26 quirks
v1.2.0	spec/TS	Complete fm-odata -> fms-odata rename (package, directory, schema, all references)
v2.0.0	spec/TS	v2.0.0 spec overhaul (versions 20-26, full endpoint/query/metadata/script/container/batch/webhook/schema/error domains)
py-v0.1.0	Python	Initial Python types package (pre-v2.0.0)
py-v2.0.0	Python	Python types package mirroring spec-ts 2.0.0
py-v2.0.1	Python	Python types package 2.0.1 (DDL and webhook endpoint corrections)
2.0.1	PHP	First PHP mirror — parity with spec-ts/Py 2.0.1

License

MIT — see LICENSE.