OCaml library for JSONfeed parsing and creation
anil.recoil.org
1# OCaml-JSONFeed
2
3An OCaml library for parsing and generating [JSON Feed](https://www.jsonfeed.org/) documents.
4
5JSON Feed is a format similar to RSS and Atom but uses JSON instead of XML.
6It is designed to be easier for developers to work with while providing all the
7functionality needed for feed syndication.
8
9## Installation
10
11Add to your `dune-project`:
12
13```lisp
14(package
15 (name your-package)
16 (depends
17 jsonfeed
18 ...))
19```
20
21## Quick Start
22
23### Creating a Feed
24
25```ocaml
26open Jsonfeed
27
28(* Create an author *)
29let author = Author.create
30 ~name:"Jane Doe"
31 ~url:"https://example.com/jane"
32 ()
33
34(* Create an item with HTML content *)
35let item = Item.create
36 ~id:"https://example.com/posts/1"
37 ~url:"https://example.com/posts/1"
38 ~title:"Hello, JSON Feed!"
39 ~content:(`Html "<p>My first post using JSON Feed.</p>")
40 ~authors:[author]
41 ~tags:["introduction"; "jsonfeed"]
42 ()
43
44(* Create the feed *)
45let feed = Jsonfeed.create
46 ~title:"My Blog"
47 ~home_page_url:"https://example.com"
48 ~feed_url:"https://example.com/feed.json"
49 ~items:[item]
50 ()
51
52(* Serialize to JSON *)
53let json = Jsonfeed.to_string feed
54```
55
56### Parsing a Feed
57
58```ocaml
59open Jsonfeed
60
61(* Parse from string *)
62match Jsonfeed.of_string json_string with
63| Ok feed ->
64 Printf.printf "Feed: %s\n" (Jsonfeed.title feed);
65 List.iter (fun item ->
66 match Item.title item with
67 | Some title -> Printf.printf "- %s\n" title
68 | None -> ()
69 ) (Jsonfeed.items feed)
70| Error (`Msg err) ->
71 Printf.eprintf "Parse error: %s\n" err
72
73(* Parse from file *)
74let content = In_channel.with_open_text "feed.json" In_channel.input_all in
75match Jsonfeed.of_string content with
76| Ok feed -> (* ... *)
77| Error _ -> (* ... *)
78```
79
80### Content Types
81
82Items can have HTML content, plain text content, or both:
83
84```ocaml
85(* HTML only *)
86let item1 = Item.create
87 ~id:"1"
88 ~content:(`Html "<p>Rich <strong>HTML</strong> content</p>")
89 ()
90
91(* Plain text only *)
92let item2 = Item.create
93 ~id:"2"
94 ~content:(`Text "Plain text content")
95 ()
96
97(* Both HTML and text *)
98let item3 = Item.create
99 ~id:"3"
100 ~content:(`Both ("<p>HTML version</p>", "Text version"))
101 ()
102
103(* Access content *)
104match Item.content_html item1 with
105| Some html -> Printf.printf "HTML: %s\n" html
106| None -> ()
107```
108
109### Podcast Feed with Attachments
110
111```ocaml
112(* Create an audio attachment *)
113let episode_audio = Attachment.create
114 ~url:"https://podcast.example.com/ep1.mp3"
115 ~mime_type:"audio/mpeg"
116 ~size_in_bytes:15_728_640L
117 ~duration_in_seconds:1800
118 ()
119
120(* Create a podcast episode *)
121let episode = Item.create
122 ~id:"https://podcast.example.com/episodes/1"
123 ~title:"Episode 1: Introduction"
124 ~content:(`Html "<p>Welcome to the show!</p>")
125 ~attachments:[episode_audio]
126 ()
127```
128
129## Examples
130
131The `example/` directory contains several complete examples:
132
133- **feed_example.ml** - Creating and serializing feeds (blog and podcast)
134- **feed_parser.ml** - Parsing and analyzing feeds from files
135- **feed_validator.ml** - Validating feeds and demonstrating various feed types
136
137Run examples:
138
139```bash
140opam exec -- dune exec -- ./example/feed_parser.exe
141opam exec -- dune exec -- ./example/feed_example.exe
142```
143
144## API Documentation
145
146Build the API documentation:
147
148```bash
149opam exec -- dune build @doc
150```
151
152Then open `_build/default/_doc/_html/index.html` in your browser.
153
154## Specification
155
156This library implements [JSON Feed Version 1.1](https://www.jsonfeed.org/version/1.1/).
157
158## License
159
160See LICENSE.md for details.