{"id":25483719,"url":"https://github.com/ameros/genyaml","last_synced_at":"2026-04-29T20:08:51.654Z","repository":{"id":220031526,"uuid":"351117346","full_name":"ameros/genyaml","owner":"ameros","description":"proposal for human-readable genealogy files stored in well-organized traversable way","archived":false,"fork":false,"pushed_at":"2022-04-13T07:46:14.000Z","size":134,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-18T13:11:55.598Z","etag":null,"topics":["gedcom","markdown","yaml"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ameros.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2021-03-24T14:49:22.000Z","updated_at":"2025-01-17T11:10:37.000Z","dependencies_parsed_at":"2024-01-31T00:14:34.090Z","dependency_job_id":"e5778894-3355-4374-a23d-10d0f825991e","html_url":"https://github.com/ameros/genyaml","commit_stats":null,"previous_names":["ameros/genyaml"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ameros/genyaml","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameros%2Fgenyaml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameros%2Fgenyaml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameros%2Fgenyaml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameros%2Fgenyaml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ameros","download_url":"https://codeload.github.com/ameros/genyaml/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameros%2Fgenyaml/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32441606,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T18:12:22.909Z","status":"ssl_error","status_checked_at":"2026-04-29T18:11:33.322Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["gedcom","markdown","yaml"],"created_at":"2025-02-18T17:47:43.445Z","updated_at":"2026-04-29T20:08:49.594Z","avatar_url":"https://github.com/ameros.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# genyaml\n\n## GEDCOM to YAML\n\n### Why\n[GEDCOM](https://en.wikipedia.org/wiki/GEDCOM) is now the de facto standard for genealogical data. However, beyond its limitations, it is full of shortcuts. Well, its purpose was to exchange genealogical data between software.\n\nHow about making it simple and **human-readable** so that anyone (also software) can write and read it.\n\n### What\nGenealogical data, as described by GEDCOM, contains between the others:\n\n- individual records (INDI)\n- family records (FAM)\n\nlinked together by references.\n![](https://docs.google.com/drawings/d/e/2PACX-1vRe0fpGo0MYDqlbQT1aQqYZOCNLF4UK9bWG6jLMIOQG3uW9v_wvfLAXPUD9HcPh4Tq4SgyWM33t4wPH/pub?w=958\u0026h=339)\nRelations are well structured so let's try to keep them the most similar. \n\n### How\nLet's start with replacing abbreviations of [Tags](http://wiki-en.genealogy.net/GEDCOM-Tags) **with real words** e.g.:\n\n| GEDCOM TAG: | replaced with: | YAML type:           | notes: |\n|-------------|----------------|----------------------|--------|\n| BIRT        | birth          | dictionary           |        |\n| DEAT        | death          | dictionary           |        |\n| BURI        | burial         | dictionary           |        |\n| MARR        | marriage       | dictionary           |        |\n| PLAC        | place          | string               |        |\n\n_...etc_\n#### Relations\nWhat if the family tree was presented in the **[YAML](https://en.wikipedia.org/wiki/YAML)** file. The simplest could look like this:\n\n```yaml\n# Yes, YAML allows us to comment\nindividuals: # GEDCOM INDI records\n  - id: I1\n    familyIds: \n      - F1\n  - id: I2\n    familyIds: \n      - F1\n  - id: I3\n    parentsId: F1\nfamilies: # GEDCOM FAM records\n  - id: F1\n    partnerIds: \n      - I1\n      - I2\n    childIds: \n      - I3\n```\n\n| GEDCOM TAG:  | replaced with: | YAML type:           | notes:                                           |\n|--------------|----------------|----------------------|--------------------------------------------------|\n| FAMS         | familyIds      | list of strings      |                                                  |\n| FAMC _{1}_   | parentsId      | string               |                                                  |\n| FAMC _{n\u003e1}_ | parents        | list of dictionaries | for different types like biological and adoption |\n| HUSB, WIFE   | partnerIds     | list of strings      |                                                  |\n| CHIL         | childIds       | list of strings      |                                                  |\n\n#### Plurals for collections\nIn the GEDCOM, there is no easy way to recognize if a record is part of a collection or just a single item. There are of course some specifications out there for different versions. But you can't tell it from just looking at the file.\n\nI think the good old convention of naming collections with a plural is a way to go _(of course a collection in YAML itself is also visible by `-` or `[]`)_ e.g.:\n\n| GEDCOM TAG: | replaced with: | YAML type:           | notes: |\n|-------------|----------------|----------------------|--------|\n| OBJE        | objects        | list of dictionaries |        |\n| TITL        | titles         | list of strings      |        |\n| OCCU        | occupations    | list of strings      |        |\n| EDU         | educations     | list of strings      |        |\n\n#### Personal Name\n[Personal Name](https://en.wikipedia.org/wiki/Personal_name) is hard thing to model. It's the set of names that the individual person is known. However, it highly depends on cultural context - synonyms, order of parts, their meaning. That's also why there is so many ideas for personal name in GEDCOM and why it still evolves there.\n\nIn GEDCOM specifications NAME can be a string / text value (with surname between slashes) or a list of such values or a list of objects. When in [5.5.1 version](https://www.tamurajones.net/GEDCOM/GEDCOM551.pdf) they can be distinguished by TYPE (one of aka | birth | immigrant | maiden | married | user defined), it is no more possible to do it in [5.5.5 version](https://www.tamurajones.net/GEDCOM/GEDCOM55Plus.pdf). However still both define NAME with number of possibilities (pieces) like NPFX, GIVN, NICK, SPFX, SURN and NSFX. \n\nThat's why my proposal is simply to use:\n\n```\nlegalFullName: Prince Rogers Nelson\nnormalShortName: Prince\notherKnownNames: [The Artist, Joey Coco, Jamie Starr]\n```\n\n| GEDCOM TAG: | replaced with:  | YAML type:           | notes: |\n|-------------|-----------------|----------------------|--------|\n| NAME        | legalFullName   | string               |        |\n|             | normalShortName | string               |        |\n|             | otherKnownNames | list of strings      |        |\n\nBy the way, I really think that a maiden name could be written as `legalFullName` but under `birth` like:\n\n```yaml\nbirth:\n  date: 28 JUL 1929\n  place: Southampton, New York, U.S.\n  legalFullName: Jacqueline Lee Bouvier\n```\n\n## Store in folders\nWorking comfortably on a family tree is not only a human-readable file, but also a well-organized storage of data. We could use a specific folder structure for this. In each such folder, we could store a piece of data about a specific person or family. Simple tooling would make it possible to produce one file from all folders. The proposal is to reflect the relations in such folders per family tree:\n\n- `individuals/{person-name-unique}/`\n- `families/{family-id}/`\n\nand place there all particular files with kind of _symlinks_ to be able to traverse the tree (folders) accordingly to relation structure.\n\n## YAML to MARKDOWN\nWhile we're here, why not use GitHub with Markdown files to conveniently navigate the tree 🤔 From the [About READMEs](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-readmes)\n\n\u003e GitHub will recognize and automatically surface your README to repository visitors.\n\nSo, if we could make simple transformation of YAML file to the README.md in each folder then we could also make use of Markdown links to refer relative folder READMEs.\n\nExample YAML file:\n\n```yaml\n# John Fitzgerald Kennedy\nid: I1\nlegalFullName: John Fitzgerald Kennedy\nnormalShortName: John F. Kennedy\notherKnownNames: [JFK, John Kennedy]\ntitles: [35th President of the United States, Senator, Congressman]\noccupations: [politician]\neducations: [Harvard University]\nbirth:\n  date: 27 MAY 1917\n  place: Brookline, Massachusetts, U.S.\ndeath:\n  date: 22 NOV 1963\n  place: Dallas, Texas, U.S.\n  cause: assassination\nburial:\n  place: Arlington National Cemetery\nobjects:\n  - file: https://upload.wikimedia.org/wikipedia/commons/thumb/c/c3/John_F._Kennedy%2C_White_House_color_photo_portrait.jpg/370px-John_F._Kennedy%2C_White_House_color_photo_portrait.jpg\n    title: John F. Kennedy, photograph in the Oval Office by Cecil Stoughton, White House; Public Domain\n    format: jpg\nfamilyIds:\n  # with Jacqueline Lee Bouvier\n  - F1\n```\n\ncould be easily transformed to such simple Markdown:\n\n```markdown\n# John Fitzgerald Kennedy\n- id: I1\n- legalFullName: John Fitzgerald Kennedy\n- normalShortName: John F. Kennedy\n- otherKnownNames: JFK, John Kennedy\n- titles: 35th President of the United States, Senator, Congressman\n- occupations: politician\n- educations: Harvard University\n- birth:\n  - date: 27 MAY 1917\n  - place: Brookline, Massachusetts, U.S.\n- death:\n  - date: 22 NOV 1963\n  - place: Dallas, Texas, U.S.\n  - cause: assassination\n- burial:\n  - place: Arlington National Cemetery\n- objects:\n  - file: ![](https://upload.wikimedia.org/wikipedia/commons/thumb/c/c3/John_F._Kennedy%2C_White_House_color_photo_portrait.jpg/370px-John_F._Kennedy%2C_White_House_color_photo_portrait.jpg)\n    - title: John F. Kennedy, photograph in the Oval Office by Cecil Stoughton, White House; Public Domain\n    - format: jpg\n- familyIds:\n  - F1 ([with Jacqueline Lee Bouvier](../../families/F1))\n```\n\nwhere the rules of transformation are easily visible and clear...\n\nAnd _**voilà**_, there we got it - **human-readable** and **well-organized** files representing family tree 🎄\n\nPlease check the example starting from [John Fitzgerald Kennedy](https://github.com/ameros/genyaml/tree/main/examples/kennedy/individuals/John-Fitzgerald-Kennedy). \n\nThere are also some templates already prepared for:\n- [individuals](templates/individuals/)\n- [families](templates/families/)\n\n---\n\nNow, all we need is just simple toolset\n- to convert from YAML to Markdown\n- from all YAML files to single one\n- and, maybe still if someone interested, from that one YAML back to GEDCOM 🤔\n\n## TBD\n\n Of course, there are many more in the GEDCOM standard (TAGS, type of RECORDS) to which the above proposal requires adjustment. Still, the base seems to be solid, and this adjustment should be easy.\n\n## Google Sheets Template\nHere comes something additional. I've just created [Google Family Tree Template](https://docs.google.com/spreadsheets/d/1Mgh86Fz51c6W2l5oUPLssexaeVqemhB1xN-zIzIToF4/edit?usp=sharing) that allows to collect GEDCOM-style data as linked sheets. You can walk it through by clicking links to parents, marriages and children. Such complete view on family tree members might be sometimes helpful and convenient.\n \n## Feedback\nAny feedback is appreciated  https://github.com/ameros/genyaml/discussions\n\n_____\nThis proposal is listed @ https://www.cyndislist.com/gedcom/gedcom-software/\n\nhttp://www.cyndislist.com/create-a-link-to-cyndis-list/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fameros%2Fgenyaml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fameros%2Fgenyaml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fameros%2Fgenyaml/lists"}