Download the PHP package fsans/fms-odata-spec-php without Composer

fms-odata-spec

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

Five projects already consume this spec:

What's in this repo

Specification documents (docs/)

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

Other contents

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.

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

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

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

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:

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 downstream wrapper repositories (fms-odata-mcp, fms-odata-js, fms-odata-py, fms-odata-php, and fms-odata-webhooks) — 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:

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:

License

MIT — see LICENSE.