MosqueStandards / prayer-data-standards

Standards for prayer time data
1 stars 0 forks source link

Discussion: Prayer Timetable JSON Schema #1

Open DilwoarH opened 1 month ago

DilwoarH commented 1 month ago

This issue will record conversions regarding discussions about JSON Document Schema for Prayer timetables.

What is a JSON Schema?

A JSON document schema is a formal definition that outlines the structure and validation rules for a JSON (JavaScript Object Notation) document. It specifies how the data within the JSON should be organized, what types of values are expected, and which fields are mandatory or optional. JSON Schema, a common standard for this, is used to validate and enforce a contract on the structure of JSON data.

Key Concepts in a JSON Schema:

  1. Data Types: Specifies the type of data each field should hold, such as string, number, array, object, boolean, etc.
  2. Properties: Defines the keys within a JSON object and specifies the data type and constraints of each key's value.
  3. Required Fields: Marks certain fields as mandatory, meaning they must be present for the JSON document to be considered valid.
  4. Constraints: Imposes rules on values, such as minimum/maximum lengths, numerical ranges, regular expressions for strings, etc.
  5. Nested Objects/Arrays: Supports defining schemas for more complex nested structures like objects within objects or arrays of objects.
  6. Default Values: Optionally provides default values for certain fields if they are not present in the JSON document.

Example JSON Schema:

Here’s a simple example of a JSON schema for a user profile:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer",
      "minimum": 0
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "isVerified": {
      "type": "boolean"
    }
  },
  "required": ["name", "email"]
}

Explanation:

Benefits of JSON Schema:

DilwoarH commented 1 month ago

API response from https://github.com/MosqueOS/Mosque-Prayer-Display-Screen

API Endpoint:

https://api.mosque.tech/mosque-data/1o9dngtGJbfkFGZK_M7xdlo2PtRuQknGEQU3FxpiPVbg

Response:

{
  "metadata": {
    "name": "East London Mosque",
    "logo_url": "https://raw.githubusercontent.com/DilwoarH/Mosque-Screen/master/src/_components/logo/assets/ELM-logo-notext-white.gif",
    "address": "82–92 Whitechapel Road, London E1 1JQ",
    "website": "eastlondonmosque.org.uk"
  },
  "jummah_times": [
    {
      "label": "Jummah 1",
      "time": "13:00"
    },
    {
      "label": "Jummah 2",
      "time": "13:45"
    },
    {
      "label": "Jummah 3",
      "time": "14:30"
    }
  ],
  "prayer_times": [
    {
      "month": "1",
      "month_label": "January",
      "day_of_month": "1",
      "sunrise_start": "08:03",
      "fajr": {
        "start": "06:26",
        "congregation_start": "06:56"
      },
      "zuhr": {
        "start": "12:09",
        "congregation_start": "12:45"
      },
      "asr": {
        "start": "13:46",
        "start_secondary": "14:16",
        "congregation_start": "14:45"
      },
      "maghrib": {
        "start": "16:05",
        "congregation_start": "16:12"
      },
      "isha": {
        "start": "17:42",
        "congregation_start": "19:30"
      }
    },
    ...
    {
      "month": "12",
      "month_label": "December",
      "day_of_month": "31",
      "sunrise_start": "08:03",
      "fajr": {
        "start": "06:26",
        "congregation_start": "06:56"
      },
      "zuhr": {
        "start": "12:09",
        "congregation_start": "12:45"
      },
      "asr": {
        "start": "13:45",
        "start_secondary": "14:16",
        "congregation_start": "14:30"
      },
      "maghrib": {
        "start": "16:04",
        "congregation_start": "16:11"
      },
      "isha": {
        "start": "17:41",
        "congregation_start": "19:30"
      }
    }
  ]
}
DilwoarH commented 1 month ago

@yousefamar - could you post an example JSON from https://sawa.global/

ohkhan commented 1 month ago

Some prior art in this space: https://github.com/MasjidiApp/MasjidiAPI Docs: https://api.masjidiapp.com/docs

Interesting endpoints

Prayer times

GET /masjids/{masjidId}/salahandiqamatimes/day/{date}

Response:

{
  "fajr_start_time": "05:57 am",
  "shuruq": "07:11 am",
  "zuhr_start_time": "12:21 pm",
  "asr_start_time": "03:52 pm",
  "magrib_start_time": "05:35 pm",
  "isha_start_time": "06:46 pm",
  "date": {
    "date": "2019-02-01 00:00:00.000000",
    "timezone_type": 3,
    "timezone": "America/Los_Angeles"
  },
  "hijri_date": {
    "day": 1,
    "month": 1,
    "year": 1443,
    "monthName": "muharram",
    "monthnameArabic": "محرم",
    "status": "sighted",
    "date": "20191202",
    "calendarID": "1"
  },
  "fajr_iqama": "06:30 AM",
  "zuhr_iqama": "01:00 PM",
  "asr_iqama": "04:15 PM",
  "maghrib_iqama": "5:30 PM",
  "isha_iqama": "08:00 PM",
  "jumma": [
    {
      "jumma_azan": "12:30 PM",
      "jumma_iqama": "01:00 PM"
    },
    {
      "jumma_azan": "02:30 PM",
      "jumma_iqama": "03:00 PM"
    }
  ]
}

Configuring Iqama Times

PUT /masjids/{masjidid}/iqamaconfig

{
  "GeneralConfig": {
    "IqamaChangeDay": "5",
    "IqamaChangeFrequency": 7,
    "IqamahChangeDates": []
  },
  "Fajr": {
    "SalahRules": [
      {
        "Type": "Predictive",
        "Applicable": "AllYear",
        "FromEndOfSalah": true,
        "MinGap": 27,
        "ChangeBy": 15,
        "MinTime": "5:00",
        "MaxTime": "6:30"
      },
      {
        "Type": "Manual",
        "Applicable": "Ramadaan"
      }
    ]
  },
  "Duhr": {
    "SalahRules": [
      {
        "Type": "Fixed",
        "Applicable": "DST",
        "Time": "13:30"
      },
      {
        "Type": "Fixed",
        "Applicable": "Standard",
        "Time": "13:00"
      }
    ]
  },
  "Asr": {
    "SalahRules": [
      {
        "FromEndOfSalah": true,
        "MinGap": 75,
        "ChangeBy": 15,
        "MinTime": "15:30",
        "MaxTime": "18:30",
        "Type": "Predictive",
        "Applicable": "DST"
      },
      {
        "MinutesAfter": 20,
        "Type": "Calculated",
        "Applicable": "Standard"
      }
    ]
  },
  "Maghrib": {
    "SalahRules": [
      {
        "MinutesAfter": "5",
        "Type": "Calculated",
        "Applicable": "AllYear"
      }
    ]
  },
  "Isha": {
    "SalahRules": [
      {
        "MinGap": 8,
        "ChangeBy": 15,
        "MinTime": "20:00",
        "MaxTime": "22:15",
        "Type": "Predictive",
        "Applicable": "Standard"
      },
      {
        "Type": "Manual",
        "Applicable": "Ramadaan"
      },
      {
        "Type": "Manual",
        "Applicable": "DST"
      }
    ]
  },
  "Jumma": [
    [
      {
        "Type": "Fixed",
        "Applicable": "Standard",
        "Time": "13:00",
        "AzanTime": "12:30"
      },
      {
        "Type": "Fixed",
        "Applicable": "DST",
        "Time": "13:30",
        "AzanTime": "13:00"
      }
    ],
    [
      {
        "Type": "Fixed",
        "Applicable": "DST",
        "Time": "13:00",
        "AzanTime": "12:30"
      },
      {
        "Type": "Fixed",
        "Applicable": "Standard",
        "Time": "13:30",
        "AzanTime": "13:00"
      }
    ],
    [
      {
        "Type": "Fixed",
        "Applicable": "DST",
        "Time": "15:45",
        "AzanTime": "15:30"
      },
      {
        "Type": "Fixed",
        "Applicable": "Standard",
        "Time": "14:00",
        "AzanTime": "13:40"
      }
    ]
  ]
}

IqamaConfig Schema:

      "IqamaConfiguration": {
        "title": "IqamaConfiguration",
        "type": "object",
        "properties": {
          "GeneralConfig": {
            "type": "object",
            "properties": {
              "IqamaChangeDay": {
                "type": "string"
              },
              "IqamaChangeFrequency": {
                "type": "string"
              },
              "IqamaChangeDates": {
                "type": "string"
              }
            }
          },
          "Fajr": {
            "type": "object",
            "properties": {
              "SalahRules": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/IqamaRule"
                }
              }
            }
          },
          "Duhr": {
            "type": "object",
            "properties": {
              "SalahRules": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/IqamaRule"
                }
              }
            }
          },
          "Asr": {
            "type": "object",
            "properties": {
              "SalahRules": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/IqamaRule"
                }
              }
            }
          },
          "Maghrib": {
            "type": "object",
            "properties": {
              "SalahRules": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/IqamaRule"
                }
              }
            }
          },
          "Isha": {
            "type": "object",
            "properties": {
              "SalahRules": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/IqamaRule"
                }
              }
            }
          },
          "Jumma": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IqamaRule"
            }
          }
        }
      },
      "IqamaRule": {
        "title": "SalahRule",
        "type": "object",
        "description": "",
        "properties": {
          "Type": {
            "type": "string",
            "enum": [
              "Predictive",
              "Fixed",
              "Manual"
            ]
          },
          "Applicable": {
            "type": "string",
            "enum": [
              "AllYear",
              "DST",
              "Standard"
            ]
          },
          "FromEndOfSalah": {
            "type": "boolean"
          },
          "MinGap": {
            "type": "number"
          },
          "ChangeBy": {
            "type": "number"
          },
          "MinTime": {
            "type": "string"
          },
          "MaxTime": {
            "type": "string"
          },
          "Time": {
            "type": "string"
          },
          "MinutesAfter": {
            "type": "number"
          },
          "AzanTime": {
            "type": "string"
          }
        },
        "required": [
          "Type",
          "Applicable"
        ]
      }
DilwoarH commented 1 month ago

Some prior art in this space: https://github.com/MasjidiApp/MasjidiAPI

Docs: https://api.masjidiapp.com/docs

Interesting endpoints

Prayer times

GET /masjids/{masjidId}/salahandiqamatimes/day/{date}

Response:


{

  "fajr_start_time": "05:57 am",

  "shuruq": "07:11 am",

  "zuhr_start_time": "12:21 pm",

  "asr_start_time": "03:52 pm",

  "magrib_start_time": "05:35 pm",

  "isha_start_time": "06:46 pm",

  "date": {

    "date": "2019-02-01 00:00:00.000000",

    "timezone_type": 3,

    "timezone": "America/Los_Angeles"

  },

  "hijri_date": {

    "day": 1,

    "month": 1,

    "year": 1443,

    "monthName": "muharram",

    "monthnameArabic": "محرم",

    "status": "sighted",

    "date": "20191202",

    "calendarID": "1"

  },

  "fajr_iqama": "06:30 AM",

  "zuhr_iqama": "01:00 PM",

  "asr_iqama": "04:15 PM",

  "maghrib_iqama": "5:30 PM",

  "isha_iqama": "08:00 PM",

  "jumma": [

    {

      "jumma_azan": "12:30 PM",

      "jumma_iqama": "01:00 PM"

    },

    {

      "jumma_azan": "02:30 PM",

      "jumma_iqama": "03:00 PM"

    }

  ]

}

Configuring Iqama Times

PUT /masjids/{masjidid}/iqamaconfig


{

  "GeneralConfig": {

    "IqamaChangeDay": "5",

    "IqamaChangeFrequency": 7,

    "IqamahChangeDates": []

  },

  "Fajr": {

    "SalahRules": [

      {

        "Type": "Predictive",

        "Applicable": "AllYear",

        "FromEndOfSalah": true,

        "MinGap": 27,

        "ChangeBy": 15,

        "MinTime": "5:00",

        "MaxTime": "6:30"

      },

      {

        "Type": "Manual",

        "Applicable": "Ramadaan"

      }

    ]

  },

  "Duhr": {

    "SalahRules": [

      {

        "Type": "Fixed",

        "Applicable": "DST",

        "Time": "13:30"

      },

      {

        "Type": "Fixed",

        "Applicable": "Standard",

        "Time": "13:00"

      }

    ]

  },

  "Asr": {

    "SalahRules": [

      {

        "FromEndOfSalah": true,

        "MinGap": 75,

        "ChangeBy": 15,

        "MinTime": "15:30",

        "MaxTime": "18:30",

        "Type": "Predictive",

        "Applicable": "DST"

      },

      {

        "MinutesAfter": 20,

        "Type": "Calculated",

        "Applicable": "Standard"

      }

    ]

  },

  "Maghrib": {

    "SalahRules": [

      {

        "MinutesAfter": "5",

        "Type": "Calculated",

        "Applicable": "AllYear"

      }

    ]

  },

  "Isha": {

    "SalahRules": [

      {

        "MinGap": 8,

        "ChangeBy": 15,

        "MinTime": "20:00",

        "MaxTime": "22:15",

        "Type": "Predictive",

        "Applicable": "Standard"

      },

      {

        "Type": "Manual",

        "Applicable": "Ramadaan"

      },

      {

        "Type": "Manual",

        "Applicable": "DST"

      }

    ]

  },

  "Jumma": [

    [

      {

        "Type": "Fixed",

        "Applicable": "Standard",

        "Time": "13:00",

        "AzanTime": "12:30"

      },

      {

        "Type": "Fixed",

        "Applicable": "DST",

        "Time": "13:30",

        "AzanTime": "13:00"

      }

    ],

    [

      {

        "Type": "Fixed",

        "Applicable": "DST",

        "Time": "13:00",

        "AzanTime": "12:30"

      },

      {

        "Type": "Fixed",

        "Applicable": "Standard",

        "Time": "13:30",

        "AzanTime": "13:00"

      }

    ],

    [

      {

        "Type": "Fixed",

        "Applicable": "DST",

        "Time": "15:45",

        "AzanTime": "15:30"

      },

      {

        "Type": "Fixed",

        "Applicable": "Standard",

        "Time": "14:00",

        "AzanTime": "13:40"

      }

    ]

  ]

}

IqamaConfig Schema:


      "IqamaConfiguration": {

        "title": "IqamaConfiguration",

        "type": "object",

        "properties": {

          "GeneralConfig": {

            "type": "object",

            "properties": {

              "IqamaChangeDay": {

                "type": "string"

              },

              "IqamaChangeFrequency": {

                "type": "string"

              },

              "IqamaChangeDates": {

                "type": "string"

              }

            }

          },

          "Fajr": {

            "type": "object",

            "properties": {

              "SalahRules": {

                "type": "array",

                "items": {

                  "$ref": "#/components/schemas/IqamaRule"

                }

              }

            }

          },

          "Duhr": {

            "type": "object",

            "properties": {

              "SalahRules": {

                "type": "array",

                "items": {

                  "$ref": "#/components/schemas/IqamaRule"

                }

              }

            }

          },

          "Asr": {

            "type": "object",

            "properties": {

              "SalahRules": {

                "type": "array",

                "items": {

                  "$ref": "#/components/schemas/IqamaRule"

                }

              }

            }

          },

          "Maghrib": {

            "type": "object",

            "properties": {

              "SalahRules": {

                "type": "array",

                "items": {

                  "$ref": "#/components/schemas/IqamaRule"

                }

              }

            }

          },

          "Isha": {

            "type": "object",

            "properties": {

              "SalahRules": {

                "type": "array",

                "items": {

                  "$ref": "#/components/schemas/IqamaRule"

                }

              }

            }

          },

          "Jumma": {

            "type": "array",

            "items": {

              "$ref": "#/components/schemas/IqamaRule"

            }

          }

        }

      },

      "IqamaRule": {

        "title": "SalahRule",

        "type": "object",

        "description": "",

        "properties": {

          "Type": {

            "type": "string",

            "enum": [

              "Predictive",

              "Fixed",

              "Manual"

            ]

          },

          "Applicable": {

            "type": "string",

            "enum": [

              "AllYear",

              "DST",

              "Standard"

            ]

          },

          "FromEndOfSalah": {

            "type": "boolean"

          },

          "MinGap": {

            "type": "number"

          },

          "ChangeBy": {

            "type": "number"

          },

          "MinTime": {

            "type": "string"

          },

          "MaxTime": {

            "type": "string"

          },

          "Time": {

            "type": "string"

          },

          "MinutesAfter": {

            "type": "number"

          },

          "AzanTime": {

            "type": "string"

          }

        },

        "required": [

          "Type",

          "Applicable"

        ]

      }

@um-developer - any insights you could share from your research?

um-developer commented 1 month ago

This is the API, we have made available and is being consumed by number of apps. Would love to partner up.