Structured Data Entity Export

Export inline JSON-LD from a small list of public HTML pages into a dataset of entity occurrences. Select types, inspect the original parsed object and trace each row to its page, script and JSON pointer.

Quick start

{
  "pageUrls": ["https://www.python.org/"],
  "schemaTypes": [],
  "maxEntities": 20
}

Omitted input, API no-body input and {} use these same defaults. {"pageUrls":[]} is an intentional empty run with no page requests. Null fields and a top-level array are invalid. The saved Python.org control contained one WebSite entity on September 9, 2026; public pages can change.

For a type-filtered example:

{
  "pageUrls": ["https://www.apple.com/"],
  "schemaTypes": ["WebSite"],
  "maxEntities": 5
}

Use pages you are authorized to retrieve. The Actor accepts at most five HTTPS URLs on port 443. It fetches static HTML directly, without a browser, login, cookies, proxy, CAPTCHA bypass or custom code. It does not crawl linked pages or request remote JSON-LD contexts.

Which objects become rows

Inline <script type="application/ld+json"> blocks are visited in page order. Media type matching ignores case and accepts parameters. The parser selects a root object, objects in a root array, and objects reached through @graph containers. Structural arrays are visited in order. Ordinary nested property objects stay inside their parent and never become additional rows.

An object containing @graph is treated as a container and never emitted itself. If it also has properties besides @context and @graph, the page receives GRAPH_CONTAINER_PROPERTIES_NOT_EXPORTED; its graph children still survive. Empty graph arrays produce no rows. Scalar array entries, invalid graphs, empty objects and context-only objects receive diagnostics.

schemaTypes matches literal, case-sensitive type values. Article, https://schema.org/Article and http://schema.org/Article match each other. Other IRIs, aliases, compact prefixes and subtypes are not inferred. A context that redefines Article does not change lexical matching. A match is not proof of Schema.org semantics.

Dataset fields

Each row contains:

• raw: the parsed entity object, with its nested structure and accepted JSON values preserved.
• types: string values observed in @type; unsupported shapes receive a diagnostic and remain available in raw.
• entityId, name, headline, description, url: values copied directly from the corresponding property (entityId uses @id). No fallback, coercion or inference. Missing properties map to null in these common fields; raw distinguishes absence from explicit null.
• provenance: zero-based pageIndex, zero-based blockIndex among JSON-LD scripts, zero-based scriptIndex among all scripts, one-based source line, zero-based source column, original normalized request URL, final URL and RFC 6901 jsonPointer. The root pointer is the empty string. /1/@graph/0 identifies the first graph object inside the second root-array element.
• occurrenceId: a SHA-256 identifier derived from that provenance. It is repeatable for unchanged source location, but can change when source layout or input order changes.
• contentHash: a SHA-256 hash of the key-sorted parsed object, without provenance or retrieval time. It identifies identical accepted content, not a verified real-world entity.
• retrievedAt: UTC time when this page's parsed rows were produced.

Repeated objects and duplicate or missing @id values are preserved as separate occurrences. Conflicting records are never merged. Identical normalized input URLs are fetched once; later input entries receive DUPLICATE_INPUT with the first index. Query strings remain significant.

Relative URLs and IDs remain exactly lexical. The Actor does not apply HTML <base>, JSON-LD @base, vocabulary expansion or URL resolution to source properties. Reported URLs are source values and may be unsafe or inaccessible; the Actor does not follow them.

raw preserves JSON values, not original whitespace, escape spelling or numeric token formatting. Duplicate object keys, non-finite values, lone Unicode surrogates, integers outside the interoperable ±(2^53-1) range and decimals that would lose value in serialization are rejected at block level. Malformed JSON is never repaired. HTML entities inside script text are not decoded a second time. JSON-LD uses the HTTP-declared charset, or strict UTF-8 when absent; unsupported encodings fail explicitly.

Outcomes and diagnostics

Only selected entity rows enter the default dataset. The OUTPUT key-value record contains per-page outcomes and block diagnostics, plus source request counters and delivery receipts.

Status	Meaning
USEFUL	Selected rows were delivered, with no reported omissions or failures.
EMPTY	The accepted pages had no matching entities, or the explicit page list was empty.
PARTIAL	Useful rows survived page/block failures, or a declared source/row/budget cap omitted work.
INVALID	Runtime input validation failed before source access. Platform schema validation may reject the request before a run starts.
FAILED	No useful row survived a source/parse failure, or delivery, receipt or persistence failed.

A malformed block receives its exact block/script location and JSON error line, column and character offset when available. Valid sibling blocks remain eligible. Diagnostics are capped and explicitly mark truncation. An HTTP error is a source failure; it is never reported as an empty schema page. INVALID and FAILED return nonzero process exit codes. Read the structured outcome even when a PARTIAL run exits successfully.

billing.deliveryStatus is NOT_ATTEMPTED, CONFIRMED or UNKNOWN. A failed or malformed append receipt produces null counts when delivery cannot be established. A later bookkeeping or OUTPUT-save failure preserves counts already confirmed. The delivery journal guards against duplicate appends: a completed journal returns its saved receipt, while an incomplete or malformed journal stops without retrying the append. These replay paths are covered by local regression tests; hosted recovery has not been demonstrated. Keep platform automatic restart disabled.

Limits

Resource	Hard maximum
Input pages	5, processed sequentially
Entity rows	200 total; default 20
Source HTTP attempts	20 across the run, including redirects and failed connections
Redirects	3 per page; every target and DNS answer is checked
Page fetch time	12 seconds total; 7-second connect/read limits
Source collection time	60 seconds, with parsing deadline checks
Response body	2 MiB encoded, 4 MiB decoded per successful page
Compression	gzip (up to 16 members), zlib deflate or Brotli; complete consumption required
JSON-LD blocks	64 per page, 256 KiB UTF-8 per block
JSON structure	Depth 32; 20,000 nodes including keys per block
Dataset row and append	128 KiB per row; 4 MiB for the batch
Diagnostics	At most 257 entries per page, including cap markers

TLS certificate verification remains enabled. DNS results must all be public; private, reserved, loopback, link-local, multicast and transition addresses are rejected. Environment proxies and cookies are disabled. Redirects do not forward credentials; credential-bearing input URLs are rejected. Responses require text/html or application/xhtml+xml. Compressed trailing corruption, truncation and decoded-size overflow fail explicitly. The source client and dataset POST client disable their pinned library retry paths. Request counts describe source fetch attempts, not DNS queries, TCP packets or Apify storage operations.

The byte caps describe response body bytes, not TLS or HTTP framing. Header field/count limits are also set. Parsing is bounded by input size, depth and nodes; wall-clock checks occur between parser chunks and blocks. Platform termination remains the outer run-time boundary.

Pricing

The price is $0.001 per delivered entity occurrence ($1 per 1,000), charged through the automatic apify-default-dataset-item event. There is no custom start, page or report event. Empty results and diagnostic records do not create entity events.

The effective row cap is the smaller of maxEntities, the SDK's remaining capacity and an exact decimal calculation from the configured event budget. At $0.001 per row, a $0.0025 event cap permits two rows. Do not use a literal zero API maximum as a no-spend control: the platform can ignore it, and positive maxima below one event may be rejected before a run starts. An explicit empty pageUrls list performs no page requests. Selected rows are appended once in a batch. An uncertain POST is never automatically retried. No claim of actual charge or delivery is made from local row selection alone.

The $0.001 entity price includes platform usage for customer runs. The event cap is not an account-wide spending ceiling. Developer/owner QA and retained-storage accounting are tracked separately, not added as another per-entity customer fee.

Scope and local development

This is inline extraction, without RDF expansion, SEO certification, truth verification, authentication, enrichment, people profiling or job-board specialization. It does not inspect markup inserted by JavaScript. Source availability, authorization and content can change. Use the raw object and provenance when evaluating the source's claims.

Run python -m src in the Actor directory after installing the hash-locked requirements in a fresh Python 3.12 environment. python run_tests.py runs the Actor-local suite; its SDK integration tests also need the matching benchmark fixtures and jsonschema==4.26.0. Deployment uses the included Dockerfile.