fsans/fms-odata-spec-php

Shared PHP types and spec definitions for the Claris FileMaker Server OData API. Mirrors @fms-odata/spec-ts (npm) and fms-odata-spec (PyPI). Types + pure helpers only; no HTTP client, no validation framework.

Maintainers

Package info

github.com/fsans/fms-odata-spec

pkg:composer/fsans/fms-odata-spec-php

Transparency log

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 1

Open Issues: 1

Security

Advisories: 0

Aikido package health analysis

2.0.1 2026-07-10 15:51 UTC

Requires

  • php: ^8.2

Requires (Dev)

MIT e739fcd9955f1d9fce090fb1962ae789e0aa925e

Published on Packagist.org on 2026-07-10 15:52 UTC

This package is auto-updated.

Last update: 2026-07-10 16:07:10 UTC

README

npm PyPI Packagist

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.