{"id":14969245,"url":"https://github.com/cucumber/microdata","last_synced_at":"2025-10-23T22:01:39.233Z","repository":{"id":37263681,"uuid":"247716053","full_name":"cucumber/microdata","owner":"cucumber","description":"Extract WHATWG microdata from a DOM","archived":false,"fork":false,"pushed_at":"2024-10-29T03:28:36.000Z","size":1865,"stargazers_count":22,"open_issues_count":4,"forks_count":6,"subscribers_count":75,"default_branch":"main","last_synced_at":"2024-10-29T14:46:47.458Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cucumber.png","metadata":{"funding":{"open_collective":"cucumber","github":"cucumber"},"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-16T13:56:42.000Z","updated_at":"2024-10-29T03:28:05.000Z","dependencies_parsed_at":"2022-07-12T05:00:49.362Z","dependency_job_id":"ac83735c-35ef-4b6c-8f50-6b522f859941","html_url":"https://github.com/cucumber/microdata","commit_stats":{"total_commits":676,"total_committers":14,"mean_commits":"48.285714285714285","dds":0.257396449704142,"last_synced_commit":"d7ef47e915da6d571652c72406b80a32406e3b0a"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cucumber%2Fmicrodata","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cucumber%2Fmicrodata/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cucumber%2Fmicrodata/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cucumber%2Fmicrodata/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cucumber","download_url":"https://codeload.github.com/cucumber/microdata/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247608159,"owners_count":20965954,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T13:41:25.618Z","updated_at":"2025-10-23T22:01:39.146Z","avatar_url":"https://github.com/cucumber.png","language":"TypeScript","funding_links":["https://opencollective.com/cucumber","https://github.com/sponsors/cucumber"],"categories":[],"sub_categories":[],"readme":"![Node.js CI](https://github.com/cucumber/microdata/workflows/Node.js%20CI/badge.svg)\n\n# Microdata\n\nThis zero-dependency library converts a DOM to [Microdata](https://html.spec.whatwg.org/multipage/microdata.html).\n\nIt can be used to extract \"interesting\" pieces of information from a DOM, such as [Person](https://schema.org/Person),\n[Order](https://schema.org/Order), [MusicEvent](https://schema.org/MusicEvent) etc.\n \nAll you need to do is to add the appropriate `itemscope`, `itemtype` and `itemprop` attributes to your HTML, and this library\nwill be able to extract the data.\n\nThe library supports [all schema.org types](https://schema.org/docs/full.html), and also allows custom Microdata types.\n\nThe returned Mircodata uses the [JSON-LD](https://json-ld.org/) format.\n\n## Installation\n\n    npm install @cucumber/microdata\n\n## Example\n\nGiven a sample DOM:\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003cdiv itemscope itemtype=\"https://schema.org/Person\"\u003e\n  \u003cspan itemprop=\"name\"\u003eJane Doe\u003c/span\u003e\n\u003c/div\u003e\n```\n\nWe can extract the `Person` on that page to a [JSON-LD](https://json-ld.org/) compliant JavaScript object:\n\n```javascript\nconst { microdata } = require('@cucumber/microdata')\n\nconst person = microdata('https://schema.org/Person', document)\nconsole.log(person.name) // \"Jane Doe\"\n```\n\nIf you are using TypeScript you can cast the result to a type from [schema-dts](https://github.com/google/schema-dts):\n\n```typescript\nimport { microdata } from '@cucumber/microdata'\nimport { Person } from 'schema-dts'\n\nconst person = microdata('https://schema.org/Person', document) as Person\nif (typeof person === 'string') throw new Error('Expected a Person object')\nconsole.log(person.name) // \"Jane Doe\"\n```\n\n## Custom value extraction\n\nIn some cases you may want finer grained control over how to extract values from the DOM. For example,\nyou may have a [CodeMirror](https://codemirror.net/) editor sitting inside of an element:\n\n```html\n\u003cdiv itemtype=\"https://schema.org/Text\"\u003e\n  \u003c!-- CodeMirror here --\u003e\n\u003c/div\u003e\n``` \n\nYou can pass a custom `extractValue` function as the last argument to `microdata` or `microdataAll`:\n\n```typescript\nconst data = microdata(\n  someSchemaType, \n  someElement,\n  element =\u003e element.querySelector('.CodeMirror')?.CodeMirror?.getValue()\n)\n```\n\nThis function may return `undefined`. In that case, the default lookup mechanisms will be used.\n\n## Custom types\n\nWe recommend using the official types defined by schema.org if you can. Sometimes however, you may want to\ndefine your own types if the official types are insufficient.\n\nYou can see an example of how this is done in [test/microdataTest.ts](test/microdataTest.ts).\n\n## Usage in testing\n\nThis library can be used to write assertions against web pages.\nIt works with any UI library as it only inspects the DOM. The only requirement\nis that the HTML has Microdata in it.\n\nHere is an example from a hypothetical TODO list application:\n\n```typescript\nimport { microdata } from '@cucumber/microdata'\n\nconst itemList = microdata('https://schema.org/ItemList', element) as ItemList\nconst todos = itemList.itemListElement as Text[]\nassert.deepStrictEqual(todos, ['Get milk', 'Feed dog'])\n```\n\n## Arrays\n\nSome microdata `itemScope`s allow `itemProp` elements that can be specified more than once.\nFor example, if an `ItemList` has two or more `itemListElement` children, then the `itemListElement`\nfield in the LD-JSON object will be an `Array`.\n\nHowever, if there is only one child, it will have the value of that child rather than an array with one element.\n\nAnd if there are none, the value of that child will be undefined.\n\nThe `toArray` function of this library will convert a value to an array with 0, 1 or more elements so you\ndon't need to worry about this.\n\n```typescript\nimport { microdata, toArray } from '@cucumber/microdata'\n\nconst itemList = microdata('https://schema.org/ItemList', element) as ItemList\nconst todos = toArray(itemList.itemListElement) as Text[]\nassert.deepStrictEqual(todos, ['Get milk', 'Feed dog'])\n```\n\n## Credit\n\nThis library is based on the excellent, but abandoned [microdata](https://github.com/nathan7/microdata). It's been ported to TypeScript, and some bug fixes have\nbeen applied to make it compliant with JSON-LD.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcucumber%2Fmicrodata","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcucumber%2Fmicrodata","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcucumber%2Fmicrodata/lists"}